Tratamento idempotente de webhooks: IDs de entrega, cronogramas de retry dos provedores e resposta rápida

O que é

Todo provedor indica um campo para deduplicação, mas o comportamento de retentativa por trás dele não é intercambiável. O ID de entrega do GitHub (X-GitHub-Delivery) identifica uma entrega, e "if you request a redelivery, the X-GitHub-Delivery header will be the same as in the original delivery." A documentação do GitHub também afirma sem rodeios: "GitHub does not automatically redeliver failed webhook deliveries, but you can handle failed deliveries manually or by writing code". Ou seja, um receptor que perde uma entrega (inclusive qualquer resposta mais lenta que 10 segundos) precisa perceber isso e disparar um reenvio pela interface ou pela API REST, que só alcança entregas recentes (as páginas do GitHub indicam hoje tanto 3 quanto 7 dias). O Stripe é o oposto: seu guia de webhooks avisa que "webhook endpoints might occasionally receive the same event more than once," recomenda registrar os IDs dos eventos já processados (e, no caso raro de dois objetos Event distintos, deduplicar pelo id de data.object combinado com event.type) e documenta retentativas automáticas "for up to three days with an exponential back off in live mode" (em sandbox, três retentativas ao longo de algumas horas); os reenvios manuais funcionam por até 15 dias no Dashboard e 30 dias pela CLI. A Events API do Slack repete "a failed request up to 3 times in a gradually increasing timetable": quase imediatamente, depois de 1 minuto e depois de 5 minutos. Cada tentativa recebe um cabeçalho x-slack-retry-num (1, 2 ou 3) e um cabeçalho x-slack-retry-reason que explica o motivo (http_timeout, http_error etc.); uma resposta não 2xx com x-slack-no-retry: 1 interrompe novas tentativas. A especificação Standard Webhooks recomenda exatamente esse padrão de forma genérica: "Use the webhook-id header as an idempotency key to prevent accidentally processing the same webhook more than once (e.g. save the IDs in redis for 5 minutes)."

Por que importa

Processar o mesmo evento duas vezes pode gerar cobrança em duplicidade, notificação em duplicidade ou alteração de estado em duplicidade. Uma política de retry que você desconhece (ou que você supôs existir e não existe) causa efeitos colaterais duplicados ou faz eventos serem descartados silenciosamente.

Como aplicar

• Persista os identificadores já processados (ID de entrega, ID do evento ou webhook-id) com uma expiração pelo menos tão longa quanto a janela de reenvio do provedor: no mínimo 7 dias para o GitHub, 3 dias para as retentativas automáticas do Stripe (até 30 dias se alguém reenviar manualmente) e mais que o intervalo de cerca de seis minutos das retentativas do Slack.
• Confirme rápido (2xx em até 10 segundos no GitHub, em até 3 segundos no Slack, "quickly" no Stripe) e execute o trabalho com efeitos colaterais depois da confirmação, em uma fila, para que uma chamada lenta a um serviço downstream não cause um timeout no provedor e, com ele, uma retentativa indesejada.
• No caso específico do GitHub, não presuma que uma entrega perdida ou com falha chegará novamente por conta própria; monte um monitoramento ou uma nova consulta agendada das entregas recentes.
• Registre nos seus logs o cabeçalho com o motivo da retentativa, quando o provedor o oferece (como o Slack); ele mostra se a retentativa foi causada pelo receptor ou pela rede.

Armadilhas

Deduplicar por um hash do payload em vez de usar o identificador do provedor: payloads podem se repetir legitimamente (duas transações idênticas de baixo valor), enquanto os IDs nunca se repetem. Outra armadilha é supor que a janela de retentativa do Stripe ou do Slack é curta o bastante para que um cache de deduplicação em memória, por processo, seja suficiente; uma reinicialização entre as retentativas perde o registro.