Definição
Um webhook é uma requisição HTTP que uma plataforma envia para uma URL informada por você sempre que ocorre um evento, como uma mensagem entregue, lida ou com falha, ou a chegada de uma resposta do cliente, para que seu sistema saiba disso na hora, sem precisar fazer polling.
Você cadastra um endpoint (por exemplo https://example.com/hooks/messaging). Quando um evento ocorre, a plataforma envia uma requisição POST com um corpo JSON que o descreve: ID da mensagem, status, timestamp, canal e detalhes de erro. Seu servidor deve responder rapidamente com um código 2xx e processar o evento de forma assíncrona.
Prepare-se para as condições reais de entrega: webhooks podem chegar atrasados, fora de ordem ou mais de uma vez. Use o ID da mensagem e o status para eliminar duplicatas, nunca faça um status retroceder (por exemplo de READ para DELIVERED) e mantenha um handler idempotente, seguro para novas tentativas.
Segurança: aceite apenas HTTPS, verifique uma assinatura ou segredo compartilhado em todas as requisições e não confie no payload até que ele seja verificado. Convenções do setor, como a especificação Standard Webhooks, descrevem padrões comuns de assinatura e de novas tentativas.
Em mensageria, os webhooks alimentam relatórios de entrega, taxas de leitura, respostas recebidas, descadastros (opt-outs) e decisões de fallback de canal.
A OmniChannels.ai envia webhooks para status de entrega (SUBMITTED, SENT, DELIVERED, READ, FAILED, REJECTED), normalizados em um único formato para todos os canais.
Exemplo
{"messageId":"msg_123","channel":"whatsapp","status":"DELIVERED","timestamp":"2026-10-10T09:15:02Z"}