Inscreva-se em eventos
Antes de começar
- Um destino HTTPS alcançável que responde rapidamente.
- A permissão
webhook.create.
1. Descubra os tipos de evento
Consulte a plataforma para os tipos de evento disponíveis em vez de trabalhar a partir de uma lista escrita em algum lugar. Uma lista transcrita se afasta do que a plataforma realmente emite.
2. Registre o webhook
Forneça o destino e os tipos de evento nos quais se inscrever.
O destino é validado antes de qualquer requisição ser feita — no registro, na atualização, no teste, e novamente na entrega. O endereço resolvido é fixado, então um destino não pode passar na validação e depois resolver para outro lugar quando um evento real dispara.
3. Teste
Dispare um teste sem esperar por um evento real. Isso confirma que o destino é alcançável e que seu consumidor interpreta o que recebe.
O resultado volta diretamente para você. Ele não é gravado no histórico de entregas, então não procure o teste lá depois.
4. Construa o consumidor corretamente
As garantias de entrega moldam como é um consumidor correto:
| Garantia | Consequência para seu consumidor |
|---|---|
| No máximo uma vez | Nada é tentado novamente de forma automática. Uma entrega falha pode ser reenviada à mão, mas nada faz isso por você — reconcilie periodicamente. |
| Tempo limite curto | Confirme rápido; faça o trabalho de forma assíncrona |
| Sem garantia de ordenação | Não assuma que eventos chegam em sequência |
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 aqui.
5. Verifique o remetente
Cada entrega carrega um segredo compartilhado para que quem recebe possa confirmar quem chama. Note que o segredo é entregue no corpo para comparação, em vez de usado para calcular um cabeçalho de assinatura. Se sua revisão de segurança exige verificação baseada em assinatura, levante isso como lacuna em vez de assumir que existe.
6. Monitore entregas
Histórico de entregas de um webhook. Uma entrega falha pode ser reenviada daqui.
Cada entrega é registrada com seu resultado. Um padrão de falhas geralmente significa que o consumidor está lento demais, não inalcançável — o tempo limite é curto.
A seguir
Última verificação no commit 1e1de1ad (2026-08-03)