Como configurar um webhook no sistema

Visão geral

A integração via webhook envia notificações automáticas em tempo real para URLs externas sempre que eventos específicos ocorrem no sistema. Essa funcionalidade permite sincronizar dados com aplicações de terceiros ou sistemas próprios de forma contínua e automatizada.

Quando usar este artigo

Utilize este artigo para cadastrar, configurar e gerenciar o disparo de eventos via webhook para URLs externas.

Sintoma ou cenário

A empresa precisa integrar o sistema com uma aplicação externa para receber dados automaticamente após a ocorrência de ações na plataforma (como alteração de dados ou novos lançamentos).

Benefício para o usuário ou operação

Disparo automático de notificações em tempo real para a URL cadastrada após cada evento selecionado;
Ciclo de reenvio automáticos em até 24 horas em caso de instabilidade no servidor de destino;
Alerta via e-mail enviado ao responsável técnico em caso de falha definitiva na entrega dos dados.

Onde acessar / contexto de uso

Acesse o menu lateral esquerdo em Apps > Webhook.

Pré-requisitos (Antes de começar)

Perfil Exato: Usuário com a permissão Webhooks - Administrativo (8500001).
Recursos Sistêmicos: Endpoint/URL de destino ativa e configurada na aplicação receptora para aceitar requisições e responder no formato esperado.
Insumos e Dados Técnicos: Definição dos eventos a serem monitorados, URL completa do endpoint receptora e e-mail para recebimento dos alertas de falha.

Causas prováveis

Necessidade de automatizar processos e sincronizar dados do sistema com plataformas externas sem dependência de consultas manuais.

Como fazer ou corrigir

Para garantir o processamento e a confirmação do envio, a aplicação de destino deve estar configurada para responder à requisição com status HTTP 200 e o corpo {"status":200} em formato JSON.

Acesse o menu lateral esquerdo e clique em Apps > Webhook.
Clique no botão Novo para iniciar uma nova configuração.
Na lista de eventos exibida, selecione aqueles que se aplicam à sua regra de negócio.
Preencha o campo de URL com o endereço da aplicação que receberá as informações.
Informe um endereço de e-mail no campo correspondente para notificações em caso de falhas de execução.
Clique no botão Salvar para finalizar.

Resultado esperado

O webhook é cadastrado e o sistema passa a enviar requisições automáticas para a URL configurada sempre que os eventos selecionados forem acionados.

Quando escalar

Escale o suporte técnico caso os disparos não ocorram mesmo com o endpoint de destino ativo e respondendo dentro do padrão JSON exigido, ou se houver erro impeditivo durante a gravação da configuração.

Informações que devem ser reunidas antes do escalonamento

Nome da licença;
URL cadastrada no webhook;
Eventos selecionados na configuração;
E-mail definido para recebimento dos alertas de erro;
Log de requisição/resposta do servidor de destino demonstrando o retorno com status HTTP 200.

Regras importantes / Observações

O sistema aguarda a resposta no formato JSON {"status":200} com código de status HTTP 200 para confirmar o sucesso do envio.
Se a URL não responder no formato correto, o sistema realizará novas tentativas automáticas distribuídas em 4 etapas: 2 tentativas após 5 minutos, 2 após 1 hora, 2 após 12 horas e 2 após 24 horas.
Caso todas as 8 tentativas falhem, uma notificação de erro será enviada para o e-mail cadastrado no webhook.

Problemas comuns e como resolver

Problema: E-mails de alerta informando falha na execução do webhook.
Causa provável: O servidor de destino está indisponível ou respondendo em formato diferente do JSON {"status":200} com código HTTP 200.
Ação recomendada: Verifique a disponibilidade da URL de destino e ajuste a resposta da aplicação para retornar exatamente a estrutura esperada.

Dúvidas relacionadas

P: O que acontece se a URL de destino estiver fora do ar no momento do evento? R: O sistema fará até 8 tentativas de reenvio divididas em intervalos de 5 minutos, 1 hora, 12 horas e 24 horas antes de enviar uma mensagem de erro por e-mail.

P: Qual é a resposta exata que o servidor receptor deve retornar para confirmar o webhook? R: O servidor deve responder com o status HTTP 200 e o corpo {"status":200} em formato JSON.

Palavras-chave de busca

configurar webhook, integração via webhook, url de retorno, eventos webhook, notificação de falha webhook, reenvio automático webhook