Pular para o conteúdo principal
Webhook é a forma de a sua aplicação ser avisada do que acontece no número: uma mensagem recebida, a confirmação de leitura, a aprovação de um template ou uma mudança na qualidade da conta. Em vez de consultar a API de tempos em tempos, a Datafy envia um POST para a sua URL assim que o evento chega da Meta. O payload é idêntico ao que a Meta envia, sem nenhuma alteração.

​
Cadastrar uma URL

No painel da Datafy, abra a aba Webhooks do número e cadastre a URL de entrega. A URL precisa usar HTTPS. As mesmas URLs também podem ser cadastradas e alteradas pela API, em Criar webhook, o que é o caminho de quem gerencia os canais pelo próprio sistema. Ao cadastrar, marque quais eventos aquela URL deve receber. Cada URL recebe apenas os eventos marcados, e é possível cadastrar mais de uma URL para o mesmo número, cada uma com a sua seleção — por exemplo, uma URL para mensagens e outra para eventos administrativos.

​
Estrutura do payload

Todos os eventos chegam no mesmo envelope. O que muda é o field, que identifica o evento, e o value, que carrega o conteúdo:
Um mesmo POST pode trazer mais de um item em entry e em changes. Percorra as duas listas em vez de ler apenas o primeiro item.

​
Headers da entrega

Os três headers acompanham todas as entregas. A verificação está em Assinatura.

​
Resposta e tempo limite

Sua URL deve responder 200 em até 20 segundos. Depois disso, a entrega é contabilizada como falha.
Responda 200 imediatamente e processe o evento em segundo plano. Processamento síncrono longo é a causa mais comum de estouro do tempo limite.

​
Reentrega automática

Quando uma entrega falha — resposta diferente de 200 ou tempo limite estourado —, a Datafy tenta de novo automaticamente. O comportamento depende do evento:
  • Eventos em tempo real (mensagens, status, templates, eventos de conta): a entrega é repetida três vezes, em 2s, 10s e 30s. Persistindo a falha, aquele evento é descartado.
  • Sincronizações de coexistência (history e smb_app_state_sync): por entregarem dados únicos e não repetíveis, a reentrega dura mais e com intervalos maiores — 10s, 1min, 5min e 30min. Detalhes em Histórico de conversas e Contatos sincronizados.
O x-datafy-delivery-id é o mesmo em todas as tentativas da mesma entrega. Use-o como chave de idempotência: se uma tentativa chegar depois de a anterior já ter sido processada, descarte a repetida pelo delivery-id.
Cada tentativa é assinada na hora, com um x-datafy-timestamp novo. Valide a assinatura sempre contra o timestamp recebido no cabeçalho daquela entrega, não contra um valor guardado.
Os eventos estão detalhados nas páginas desta seção, começando por Mensagens recebidas. A lista completa de eventos da plataforma está na documentação de webhooks da Meta.