Referência de eventos
Configurações de webhook
Assinaturas de webhook. As configurações abaixo são o que cada linha carrega.
| Configuração | Finalidade |
|---|---|
| Destino | Para onde as entregas são enviadas |
| Tipos de evento | O que dispara uma entrega |
| Segredo | Valor compartilhado que quem recebe usa para verificar quem chama |
| Ativo | Se entregas são tentadas |
Comportamento de entrega
| Propriedade | Valor |
|---|---|
| Semântica | No máximo uma vez — sem nova tentativa automática; uma entrega falha pode ser reenviada manualmente |
| Tempo limite | Curto; um consumidor lento é uma entrega falha |
| Ordenação | Não garantida |
| Impacto de falha | Nenhum sobre a operação de origem, que já foi confirmada |
| Registro | Entregas reais e reenvios manuais são registrados com seu resultado. Um disparo de teste não — seu resultado é devolvido a você na hora e não é armazenado em lugar nenhum, então nunca aparece no histórico de entregas. |
| Sinal de sucesso | Uma resposta 2xx, que também emite uma entrada de auditoria |
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. Um destino recusado emite uma entrada de auditoria de segurança.
Isso existe porque um webhook é uma requisição de saída para um endereço que uma organização fornece, o que de outro modo é uma rota para infraestrutura interna.
Proteção contra laço
Eventos sobre webhooks nunca são entregues. Um webhook inscrito nos próprios tipos de evento não pode causar uma tempestade de realimentação.
Limitações atuais
Declare-as abertamente em vez de descobri-las em produção:
| Limitação | Consequência |
|---|---|
| Sem nova tentativa automática | Uma entrega falha permanece falha até alguém reenviá-la. Reconcilie contra a API. |
| Segredo armazenado como fornecido | Trate-o como segredo compartilhado, não como credencial |
| Sem cabeçalho de assinatura | O segredo viaja no corpo para comparação |
| Sem rotação de chave por organização | Rotacione atualizando o webhook |
Se sua revisão de segurança exige verificação baseada em assinatura, levante isso como lacuna. É um pedido razoável; não está presente hoje.
A seguir
Última verificação no commit 1e1de1ad (2026-08-03)