Todo sistema que integra webhooks, seja para receber notificações de pagamento, atualizações de status ou qualquer outra ação, enfrenta o desafio de garantir a entrega e processamento de eventos de forma confiável. Este artigo explora as principais desafios e soluções para criar uma arquitetura robusta de webhooks.
Ponto 1: Responder Rápido e Processar Depois
A primeira abordagem comum é:
- POST /webhook: valida, libera acesso, envia e-mail, responde 200
Mas isso pode resultar em ambiguidade. Se a validação e envio de e-mail demoram, o gateway pode considerar falha, mesmo que o processamento final termine. Para resolver isso, é necessário separar a recepção do processamento:
- POST /webhook: grava o evento, responde 200 imediatamente, e envia para um worker para processamento.
Isso introduz a necessidade de uma fila (ou uma tabela de eventos funcionando como fila) para armazenar os eventos temporariamente.
Ponto 2: Idempotência
Para evitar que um evento seja processado mais de uma vez, é necessário garantir que cada evento tenha uma chave estável. Por exemplo, em uma plataforma de pagamento como a Kiwify, onde o envelope muda com cada reenvio, usar o ID do pedido/venda como chave de idempotência é uma boa prática. Isso garante que um evento só seja processado uma vez.
Ponto 3: Retorno Exponencial (Retorno com Backoff)
Para lidar com falhas temporárias do destino final, é necessário implementar um backoff exponencial. Se o destino estiver fora do ar, o worker espera um intervalo crescente (1min, 5min, 15min, 1h) antes de tentar novamente. Se não houver sucesso após N tentativas, o evento é movido para uma fila morta (Dead Letter Queue) para análise manual.
Conclusão
Para garantir a confiabilidade de webhooks em sistemas distribuídos, é crucial implementar uma arquitetura que inclui uma fila, idempotência por chave estável, retratação com backoff exponencial e uma fila morta. Essas soluções juntas garantem que nenhum evento seja perdido e permitem a manutenção de um sistema resiliente mesmo em momentos de alta carga.