Publicando eventos
Sistemas a jusante precisam saber quando um registro governado muda — quando um registro dourado é atualizado, quando registros se consolidam, quando uma solicitação de privacidade é concluída. Webhooks entregam essas notificações.
Como funciona
Assinaturas de webhook, cada uma com o destino e os tipos de evento a que está inscrita.
Registre um endpoint, inscreva-o nos tipos de evento que lhe interessam, e a plataforma faz uma requisição a ele quando ocorrerem. Cada entrega é registrada com seu desfecho, então você vê o que foi enviado e o que aconteceu com ela.
Tipos de evento são descobríveis
O conjunto de tipos de evento disponíveis é servido pela plataforma, em vez de documentado como uma lista estática aqui. Consulte-o e inscreva-se no que encontrar — uma lista escrita na documentação divergiria do que a plataforma de fato emite.
Proteção de requisições de saída
Um webhook é uma requisição HTTP de saída para um endereço que você fornece, o que o torna um vetor potencial para alcançar infraestrutura interna. Destinos são validados antes de qualquer requisição, em todos os pontos de entrada — criar um webhook, atualizá-lo, testá-lo, reenviá-lo manualmente e entregar a ele.
A validação fixa o endereço resolvido, então um destino não pode passar na validação e depois resolver para outro lugar no momento da entrega. Um destino rejeitado é registrado como evento de segurança.
Semântica de entrega
Esteja ciente do comportamento atual ao projetar um consumidor:
- A entrega é no máximo uma vez. Não há reenvio automático; uma entrega falha é registrada e permanece falha até ser reenviada explicitamente.
- Entregas têm um tempo limite curto. Um consumidor lento é tratado como falha.
- Falhas de entrega nunca afetam a operação de origem. A mudança já foi confirmada.
- Eventos sobre webhooks nunca são eles próprios entregues, então um webhook inscrito nos próprios tipos de evento não causa laço de realimentação.
Com entrega no máximo uma vez, um consumidor que trate webhooks como um fluxo completo de mudanças acabará perdendo algo. Trate-os como uma notificação de baixa latência e reconcilie periodicamente contra a API para correção.
Segredos
Um webhook carrega um segredo compartilhado para que o receptor verifique quem chama. Note que o segredo é entregue no corpo da requisição para comparação, em vez de usado para calcular um cabeçalho de assinatura. Se você precisa de verificação por assinatura, trate isso como uma lacuna a levantar, não como algo já presente.
Testes
Um webhook pode ser disparado em teste sem esperar por um evento real, que é a forma mais rápida de confirmar que o destino é alcançável e que seu consumidor interpreta o que recebe.
A seguir
Última verificação no commit d3c2586b (2026-08-03)