Resposta curta
Para receber relatórios de entrega por webhook, exponha um endpoint HTTPS que aceite requisições POST e registre a URL no seu fornecedor de mensagens. Grave cada evento, responda rápido com status 2xx e processe de forma assíncrona. Relacione os eventos aos seus registros pelo ID da mensagem, elimine duplicatas e nunca deixe um status atrasado sobrescrever um final.
Configure o endpoint
Durante o desenvolvimento, um túnel dá a um servidor local uma URL HTTPS pública.
- Exponha um endpoint HTTPS que aceite requisições POST com corpo JSON.
- Informe a URL ao fornecedor para que ela seja configurada na conta ou subconta correta.
- Envie uma mensagem de teste para o seu próprio número e registre o corpo bruto do evento.
- Mapeie os campos necessários a partir de eventos reais, não de nomes de campo supostos.
- Guarde payloads de exemplo como fixtures de teste para cada canal que você usa.
Quais status você vai receber?
Os fornecedores traduzem os comprovantes das operadoras e dos canais para nomes de status próprios. Este conjunto padronizado é o que a OmniChannels.ai usa em SMS, WhatsApp e outros canais.
| Status | Significado | Final? |
|---|---|---|
| SUBMITTED | Aceita e na fila | Não |
| SENT | Repassada à operadora ou ao canal | Não |
| DELIVERED | Confirmada no aparelho | Em geral; pode vir READ depois |
| READ | Aberta, em canais que informam leitura | Sim |
| FAILED | Não entregue, com motivo quando disponível | Sim |
| REJECTED | Recusada, por exemplo por ID de remetente (Sender ID) sem registro | Sim |
Deixe o handler confiável
- Grave o corpo bruto e depois responda 2xx. Se a gravação falhar, responda 5xx para que o evento seja reenviado.
- Faça o processamento real em uma fila ou worker, não antes de responder.
- Elimine duplicatas pelo ID da mensagem; o mesmo status pode chegar duas vezes.
- Classifique os status por ordem para que um SENT atrasado nunca sobrescreva um DELIVERED.
- Aceite valores de status desconhecidos em vez de gerar erro.
- Nunca reenvie uma mensagem de dentro do handler do webhook.
Proteja o endpoint e recupere relatórios perdidos
Aceite só HTTPS, use um caminho longo e difícil de adivinhar, valide a estrutura do corpo e confirme o estado com uma consulta de status antes de ações irreversíveis, como reembolsos. Se o seu endpoint ficou fora do ar, peça ao fornecedor para reenviar os comprovantes do período ou consulte os status nos endpoints de relatório dele.
Via SMPP, os comprovantes chegam como deliver_sm no bind, e não por webhook. Algumas operadoras devolvem comprovantes com atraso ou nem devolvem, então trate-os como forte indício, não como prova de leitura.