Gestión idempotente de webhooks: IDs de entrega, calendarios de reintento de cada proveedor y respuesta rápida

Qué es

Cada proveedor indica un campo sobre el que deduplicar, pero el comportamiento de reintento que hay detrás no es intercambiable. El ID de entrega de GitHub (X-GitHub-Delivery) identifica una entrega, y "if you request a redelivery, the X-GitHub-Delivery header will be the same as in the original delivery." La documentación de GitHub también lo dice sin rodeos: "GitHub does not automatically redeliver failed webhook deliveries, but you can handle failed deliveries manually or by writing code". Por tanto, un receptor que pierde una entrega (incluida cualquier respuesta que tarde más de 10 segundos) debe detectarlo y provocar una reentrega desde la interfaz o la API REST, que solo alcanza entregas recientes (las páginas de GitHub indican actualmente tanto 3 como 7 días). Stripe es lo contrario: su guía de webhooks advierte de que "webhook endpoints might occasionally receive the same event more than once", recomienda registrar los IDs de los eventos procesados (y, para el caso poco frecuente de dos objetos Event distintos, deduplicar por el id de data.object más event.type) y documenta reintentos automáticos "for up to three days with an exponential back off in live mode" (tres reintentos a lo largo de unas horas en un sandbox); los reenvíos manuales funcionan hasta 15 días en el Dashboard y hasta 30 días mediante la CLI. La Events API de Slack reintenta "a failed request up to 3 times in a gradually increasing timetable": casi de inmediato, luego al cabo de 1 minuto y después de 5 minutos. Además marca cada intento con una cabecera x-slack-retry-num (1, 2 o 3) y una cabecera x-slack-retry-reason que explica el motivo (http_timeout, http_error, etc.); una respuesta que no sea 2xx y que incluya x-slack-no-retry: 1 detiene los intentos posteriores. La especificación Standard Webhooks recomienda exactamente este patrón 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 qué importa

Procesar el mismo evento dos veces puede duplicar un cobro, duplicar una notificación o modificar el estado dos veces. Una política de reintentos que se desconoce (o la ausencia de una que se daba por supuesta) provoca efectos secundarios duplicados o hace que se pierdan eventos sin que nadie lo note.

Cómo aplicarlo

• Almacena los identificadores procesados (ID de entrega, ID de evento o webhook-id) con una caducidad al menos igual a la ventana de reentrega del proveedor: como mínimo 7 días para GitHub, 3 días para los reintentos automáticos de Stripe (hasta 30 días si alguien reenvía manualmente) y más que el intervalo de reintentos de unos seis minutos para Slack.
• Confirma la recepción rápido (2xx en menos de 10 segundos para GitHub, en menos de 3 segundos para Slack, "quickly" para Stripe) y ejecuta el trabajo con efectos secundarios después de la confirmación, en una cola, de modo que una llamada lenta a un servicio posterior no provoque un timeout en el proveedor que desencadene un reintento no deseado.
• En el caso concreto de GitHub, no des por hecho que una entrega perdida o fallida vaya a llegar de nuevo por sí sola; crea monitorización o una consulta periódica de las entregas recientes.
• Registra en tus logs la cabecera con el motivo del reintento cuando el proveedor la ofrezca (como la de Slack): indica si el reintento lo causó el receptor o la red.

Trampas

Deduplicar por un hash del payload en lugar de por el identificador del proveedor: los payloads pueden repetirse legítimamente (dos transacciones idénticas de poco valor), mientras que los IDs nunca se repiten. Asumir que la ventana de reintentos de Stripe o de Slack es lo bastante corta como para que baste una cache de deduplicación en memoria por proceso: un reinicio entre reintentos hace perder el registro.