Los reintentos de webhooks y la idempotencia van de la mano. Un emisor que no recibe una respuesta 2xx a tiempo vuelve a enviar el mismo evento, así que tu receptor verá a veces un mismo evento dos veces. Haz el manejador idempotente: confirma rápido, pon el trabajo en cola y registra el id de cada entrega para que una repetición se reconozca y se omita.
Al recibir una integración, trato cada webhook como algo que puede llegar más de una vez. Un manejador que hace todo el trabajo dentro de la petición acabará, tarde o temprano, haciéndolo dos veces.
¿Por qué los emisores de webhooks reintentan el mismo evento?
Un emisor reintenta porque no puede distinguir una petición perdida de una respuesta perdida. Si tu servidor hizo el trabajo y luego la conexión se cortó, o si tu respuesta llegó después del tiempo de espera del emisor, el emisor registra un fallo y vuelve a enviar el evento.
RFC 9110, el estándar de semántica de HTTP, indica que PUT, DELETE y los métodos seguros son idempotentes; POST no está entre ellos. Un cliente no debería reintentar automáticamente una petición no idempotente a menos que pueda saber que es idempotente, o detectar que la original nunca se aplicó. Un emisor que reintenta un POST depende de que el receptor lo haga idempotente, y un id de entrega que permanece igual en cada intento permite al receptor hacerlo.
¿Por qué usar una cola para los webhooks?
Una cola permite que el manejador responda en milisegundos y haga el trabajo lento después, de modo que el tiempo de espera del emisor nunca compite con tu lógica de negocio.
- Verifica la firma contra el cuerpo sin procesar, si el emisor firma sus llamadas.
- Inserta el id de entrega y el cuerpo sin procesar en una tabla con una clave única sobre el id de entrega.
- Responde 2xx. RFC 9110 define 202 Accepted para este caso: aceptado para su procesamiento, procesamiento no completado.
- Un worker lee el evento almacenado, hace el trabajo y marca la fila como terminada.
Si la inserción choca con la clave única, ya tienes el evento: responde 2xx y no hagas nada más. Una respuesta de error ante un duplicado genera más reintentos. Es la misma idea que la clave única por dispositivo y marca de tiempo en un escritor de base de datos MQTT. Si la inserción falla porque la base de datos está caída, responde con un error para que el emisor vuelva a intentarlo más tarde.
¿Qué ocurre si un endpoint de webhook está caído?
El emisor reintenta según su propio calendario y después se detiene. Los intentos y las esperas varían de un emisor a otro, así que lee su documentación antes de planificar una ventana de mantenimiento.
Los eventos reintentados llegan tarde y pueden llegar desordenados, así que ordénalos por las marcas de tiempo del payload, no por el orden de llegada. Para una caída prolongada, mantén una lectura de recuperación a través de la API del emisor, como en webhook vs WebSocket vs polling.
Hermetry conecta dispositivos de campo con paneles en vivo, reglas y alertas: telemetría IoT y SCADA en una sola plataforma. Sus webhooks incluyen un id X-Webhook-Delivery que es el mismo en cada reintento y reenvío, y las entregas son al menos una vez, sin un orden garantizado. Por defecto, una entrega tiene 3 intentos, contando el primero, con esperas de 60.000 ms y 300.000 ms antes de los reintentos. Tras 10 fallos seguidos, el endpoint se desactiva; cuando un administrador lo vuelve a activar, lo que falló puede volver a entregarse o reproducirse.
Antes de escribir el worker, consulta en la documentación de eventos del emisor, como una referencia de eventos de webhook, qué campo contiene la hora del evento.
¿Cómo pruebas un webhook en localhost?
Un emisor en internet no puede acceder a localhost, así que reproduce primero los payloads grabados contra tu manejador local y luego haz una comprobación de extremo a extremo a través de una dirección HTTPS pública.
- Graba una entrega real, con cabeceras y cuerpo sin procesar, y reprodúcela dos veces con un cliente HTTP de línea de comandos. La segunda llamada debería recibir un 2xx y no causar ningún efecto secundario.
- Si tu manejador rechaza marcas de tiempo antiguas, firma las repeticiones con un secreto de prueba y envía una marca de tiempo caducada para comprobar que se rechaza.
Un túnel que asigna a tu máquina una dirección HTTPS pública temporal cubre la comprobación de extremo a extremo. Lo cierro cuando la prueba pasa.
Preguntas frecuentes
¿Es idempotente un POST de webhook por defecto?
No. RFC 9110 indica que PUT, DELETE y los métodos seguros son idempotentes, y POST no está entre ellos. Un POST de webhook solo se vuelve idempotente cuando el receptor lo hace así, por ejemplo guardando el id de entrega bajo una clave única y omitiendo las repeticiones.
¿Cuánto tiempo debo conservar los ids de entrega?
Como mínimo, mientras el emisor pueda seguir reintentando o reenviando el evento; un reenvío manual, cuando el emisor lo ofrece, puede llegar días después. Cada id es una cadena corta, así que los conservo durante semanas.
¿Puedo deduplicar por el payload en lugar de por un id de entrega?
Solo como alternativa. Dos eventos genuinos pueden tener payloads idénticos, por ejemplo un valor que cruza dos veces el mismo límite. Sin un id de entrega, construye una clave a partir del tipo de evento, el id de origen y la marca de tiempo propia del evento.

