Webhook é mensagem HTTP assíncrona, não chamada de função garantida. O emissor pode repetir, eventos chegam atrasados ou fora de ordem, seu endpoint pode cair e um handler lento provocar nova entrega. Uma integração robusta espera duplicatas e torna cada etapa visível e recuperável.
Não execute o fluxo de negócio lento antes da confirmação. O GitHub, por exemplo, espera resposta 2xx em até 10 segundos e recomenda fila assíncrona para trabalho demorado. Esse prazo varia por provedor: confira contrato de entrega e repetição de cada integração.
Use HTTPS e valide a assinatura sobre o corpo bruto exato antes de interpretar ou alterar estado. Guarde segredo em cofre, compare MAC em tempo constante e planeje rotação com sobreposição controlada. Quando o esquema incluir timestamp, valide a janela. Allowlist de IP é defesa adicional, não substitui assinatura; faixas podem mudar.
Imponha limite de corpo, tipo de conteúdo, segredo por endpoint e tipos de evento esperados. Não coloque credenciais na URL. Assinatura válida comprova remetente e integridade do payload, não que cada campo seja seguro ou que o evento pertença ao cliente correto.
| Identificador | Uso | Não presuma |
|---|---|---|
| ID de entrega do provedor | Deduplicar retry de transporte e rastrear suporte. | Que representa a mesma ação de negócio em qualquer provedor. |
| Objeto/versão de negócio | Validar transição e versão da origem. | Que eventos chegam na ordem de criação. |
| ID interno de processamento | Correlacionar tentativas, efeitos e logs. | Que retry é evento de negócio novo. |
Persista o ID do provedor com restrição de unicidade. Alguns emissores reutilizam o mesmo ID numa redelivery manual; se suporte precisar, guarde tentativas à parte. Eventos diferentes ainda podem representar a mesma transição, então idempotência também pertence à operação de negócio.
Grave a entrega antes de responder sucesso. Outbox transacional ou dispatcher recuperável evita perder processamento se o processo cair entre commit e publicação na fila. O consumidor registra estado e também torna idempotentes efeitos externos: passe chave idempotente a APIs de pagamento/e-mail/CRM quando suportado ou mantenha ledger local. Transação SQL não torna atômica uma chamada HTTP independente.
Repita falhas transitórias de rede, rate limit e dependência com backoff exponencial e jitter, respeitando Retry-After quando houver. Não repita para sempre erro permanente de esquema ou permissão. Após política limitada, mova a mensagem para dead letter/quarentena com motivo, tentativas e horários. Alerte sobre idade da fila e falhas repetidas; dead letter sem monitoramento só esconde o problema.
Use versão da origem, horário de atualização ou regra de domínio quando a ordem importar. Busque estado atual na origem em transições críticas, se o contrato permitir. Não aplique cancelamento antigo sobre reativação mais nova só porque chegou depois. Registre horário do provedor, recebimento e processamento para diagnosticar atraso.
Operadores precisam localizar por ID do provedor, cliente, tipo, objeto e período; inspecionar verificação e processamento; tentar novamente sem repetir efeitos e comparar com a origem. Replay mantém identidade original e ganha registro de tentativa. Redija dados pessoais dos logs e defina retenção do payload. Reconciliação encontra eventos nunca entregues ou retries esgotados.
Teste assinatura inválida, alteração do corpo, duplicatas, dependência lenta, indisponibilidade de banco/fila, queda após commit, rate limit, redelivery, ordem trocada e payload venenoso. Confirme que a resposta ocorre só após aceitação durável e que repetir não duplica efeitos. Use sandbox e ferramentas do provedor antes de produção.
Webhook confiável usa entrada autenticada curta, aceitação durável, confirmação rápida, processamento assíncrono idempotente, retries limitados, dead letters visíveis e replay seguro. Essa arquitetura discreta importa porque pagamento, provisionamento e estado do cliente não podem depender de uma única requisição chegar no momento perfeito.