Operações de Webhook
Webhooks são o plano de controle. Esta página é o modelo operacional de webhook publicado para a plataforma.Princípios-Chave
- Verifique cada entrega. A Meta usa
X-Hub-Signature-256; hooks de parceiros podem usar HMAC ou tokens estáticos. - Persista os envelopes brutos. Mantenha headers, hash do body, parâmetros de query e metadados de tenant/provider com políticas de retenção.
- Normalize para famílias de eventos conhecidas. Use
provider.message.inbound,.status,.template.updated,.conversation.updated, etc. - Faça replay com segurança. Cada replay cria um novo registro de tentativa sem alterar o envelope original.
- Trate duplicados. Deduplique pelo delivery ID, mas mantenha o timestamp mais recente e permita replay manual quando ocorrerem melhorias legítimas.
Modelo de Envelope
Cada envelope registra:- tenant, provider, escopo do provider (WABA ou número de telefone)
- família do evento, ID de evento externo, delivery ID
- status de verificação e normalização
- headers/parâmetros de query/hash do body/body bruto
- status de resposta e metadados de replay
Endpoints Operacionais
GET /internal/webhooks– filtra por tenant, tipo, cursor.GET /internal/webhooks/:id– inspeciona headers, body, status do evento normalizado.GET /internal/webhook-rejections,/internal/webhook-rejections/:id– forense.POST /internal/webhooks/:id/replay– reprocessa após aprovação do operador.GET /internal/runtime– profundidade de fila, atraso dos workers, tendências de backlog.
Monitoramento
- Latência: meta de mediana
abaixo de 250 ms, commenos de 1%das requisições acima de1 s. - Contagem de rejeições e replays.
- Profundidade de fila e heartbeat dos workers.
- Taxas de falha na validação de templates.
- Violações de guardrail de pair-rate e throughput.