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 fixá-los no código — o que ela emite muda conforme o produto cresce.
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. 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.