Configuração de Webhooks: eventos, entregas e segurança - Ajuda

A tela de Webhooks configura notificações HTTP automáticas para sistemas externos. Quando um evento selecionado acontece no CRM, uma entrega é preparada para o endereço cadastrado.

Como acessar

No CRM, acesse Configurações → Integrações → Webhooks.

Para visualizar os webhooks e seus históricos, é necessária a permissão de acesso às configurações da API. Criar, ativar, desativar ou excluir exige a permissão de gerenciamento da API. A clínica também deve possuir o módulo API Pública ativo.

Eventos disponíveis

É possível receber notificações para:

lead.created: criação de um lead.
appointment.created: criação de um agendamento.
appointment.cancelled: cancelamento de um agendamento.

Cadastrando um webhook

Clique em Novo webhook.
Informe a URL do sistema que receberá as notificações.
Marque um ou mais eventos.
Confirme a criação.

A URL deve ser válida e usar obrigatoriamente https://. Não é possível criar um webhook sem selecionar pelo menos um evento.

Segredo e assinatura HMAC

Ao criar o webhook, o CRM gera um segredo iniciado por whsec_. Ele é exibido uma única vez; copie-o antes de fechar a janela e armazene-o com segurança no servidor de destino.

Cada entrega inclui estes cabeçalhos:

X-Webhook-Signature: assinatura no formato sha256=<hmac>.
X-Webhook-Event: evento que originou a entrega.
X-Webhook-Delivery: identificador único da entrega.

O sistema receptor deve calcular o HMAC-SHA256 sobre o corpo bruto da requisição, usando o segredo do webhook, e comparar o resultado com X-Webhook-Signature antes de processar os dados.

Use X-Webhook-Delivery para evitar processar a mesma entrega duas vezes. Não registre o segredo nem payloads com dados pessoais em logs desprotegidos.

Lista e histórico

A lista mostra a URL, os eventos inscritos, o status e a atividade mais recente. A ação de histórico apresenta as últimas 30 entregas, com:

Evento.
Situação da entrega.
Código HTTP retornado, quando disponível.
Data e hora.

A tela não possui um botão para disparar uma entrega de teste. Para validar a integração, gere um evento controlado e acompanhe o histórico.

Respostas, novas tentativas e desativação automática

O endpoint deve responder com um código HTTP da faixa 2xx para que a entrega seja considerada bem-sucedida.

Quando ocorre uma falha, o CRM realiza novas tentativas com intervalos progressivos. Depois que as tentativas de uma entrega se esgotam, a falha passa a contar para o webhook. Após 15 falhas consecutivas concluídas, o webhook é desativado automaticamente.

As entregas são processadas em segundo plano, normalmente em poucos instantes; não devem ser tratadas como comunicação instantânea.

Ativar, desativar e excluir

Desativar: interrompe novos envios sem apagar a configuração.
Reativar: retoma os envios e zera o contador de falhas consecutivas.
Excluir: remove definitivamente o webhook e seu histórico associado.

Se um webhook foi desativado automaticamente, corrija primeiro o endpoint, o certificado HTTPS e o tratamento da assinatura. Depois, reative-o e acompanhe as próximas entregas.