Eventos em resumo
Semântica de entrega
| Propriedade | Valor |
|---|---|
| Semântica | No máximo uma vez — sem nova tentativa automática |
| Tempo limite | Curto; um consumidor lento é uma entrega falha |
| Ordenação | Não garantida |
| Impacto de falha | Nenhum — a mudança já foi confirmada |
| Registro | Entregas reais e reenvios manuais são registrados; um disparo de teste não |
Uma entrega falha pode ser reenviada manualmente, mas nada a reenvia por você.
O que um consumidor correto faz
Com entrega no máximo uma vez, um consumidor que assume ver todos os eventos acabará errado — e não saberá disso.
Trate webhooks como uma notificação de baixa latência de que algo mudou, e reconcilie contra a API para correção. Esta é a coisa mais consequente a acertar.
- Confirme rápido; faça o trabalho de forma assíncrona.
- Não assuma ordenação.
- Reconcilie periodicamente.
Validação de destino
Validado em cinco pontos: criação, atualização, disparo de teste, nova tentativa manual, e entrega. O endereço resolvido é fixado, então um destino não pode passar na validação e depois resolver para outro lugar no momento da entrega.
Isso existe porque um webhook é uma requisição de saída para um endereço que uma organização fornece — do contrário, uma rota para infraestrutura interna. Um destino recusado emite uma entrada de auditoria de segurança.
Proteção contra laço
Eventos sobre webhooks nunca são entregues, então um webhook inscrito nos próprios tipos de evento não pode causar uma tempestade de realimentação.
Limitações atuais
Declaradas abertamente em vez de descobertas em produção:
| Limitação | Consequência |
|---|---|
| Sem nova tentativa automática | Uma entrega falha permanece falha até ser reenviada |
| Segredo armazenado como fornecido | Um segredo compartilhado, não uma credencial |
| Sem cabeçalho de assinatura | O segredo viaja no corpo para comparação |
Se sua revisão de segurança exige verificação baseada em assinatura, levante isso como lacuna. É razoável; não está presente hoje.
Descubra tipos de evento
Consulte a plataforma em vez de trabalhar a partir de uma lista escrita.
A seguir
Última verificação no commit d3c2586b (2026-08-03)