Un proveedor envía un evento, tu aplicación actualiza un pedido y la respuesta HTTP se pierde. El proveedor puede volver a entregar el mismo evento. Si cada entrega ejecuta otra vez la acción, una comunicación aparentemente correcta termina creando efectos duplicados.
Un webhook fiable necesita un contrato de recepción y recuperación. Esta lista utiliza un cambio de estado de pedido como ejemplo construido; las reglas de entrega y firma deben obtenerse del proveedor concreto.
1. Verifica la autenticidad antes de aceptar el contenido
Comprueba la firma mediante el procedimiento documentado por el emisor y protege el secreto utilizado. Cuando la firma cubre los bytes originales de la petición, transformar el JSON antes de verificarla puede invalidar la comprobación.
La documentación de webhooks de Stripe explica su validación sobre el cuerpo original y sus reglas de reentrega. Es una referencia útil para entender el problema, pero no establece el contrato de otros proveedores.
Si el mecanismo incorpora una marca temporal, aplica su tolerancia y utiliza un reloj correctamente sincronizado. Una firma válida no sustituye la comprobación de que la cuenta emisora y el recurso pertenecen a la organización esperada.
2. Conserva la recepción antes de confirmar
Define qué significa responder con éxito: por ejemplo, que el evento se ha almacenado de forma duradera y puede procesarse aunque el receptor se reinicie.
No confirmes la recepción tras introducir el evento únicamente en una estructura de memoria si un reinicio lo perdería. Tampoco mantengas la conexión abierta mientras ejecutas operaciones largas cuando el emisor espera una respuesta rápida.
Una bandeja de entrada persistente puede guardar identidad del emisor, identificador del evento, tipo, fecha de recepción y estado de procesamiento. Conserva el contenido necesario con permisos y retención adecuados; evita copiarlo íntegro a los registros de diagnóstico.
3. Deduplica la entrega sin confundir eventos distintos
La misma identidad de evento debe reconocer una reentrega. En una plataforma con varias cuentas, delimita la clave por proveedor y cuenta cuando sus garantías de unicidad lo requieran.
La comprobación y el registro necesitan una garantía atómica. Dos peticiones simultáneas no deben superar a la vez un simple “si no existe, insertar”.
Distingue duplicado de transporte y duplicado de negocio. Dos eventos con identificadores distintos pueden comunicar cambios sobre el mismo recurso. Eliminarlos porque comparten el pedido podría descartar una actualización legítima.
Si el procesamiento llama a otra API, relaciona la operación con una clave de idempotencia estable cuando el destino soporte ese contrato.
4. Decide qué hacer cuando el orden cambia
Un evento recibido después no tiene por qué representar el estado más reciente. No ordenes cambios únicamente por la hora de llegada a tu servidor.
Para el pedido del ejemplo, utiliza una versión comparable cuando el proveedor la ofrezca. Otra opción es consultar el estado autorizado del recurso y reconciliarlo, si esa API existe y sus garantías sirven al proceso.
Si necesitas reconstruir toda la secuencia histórica, consultar solo el estado actual no recupera los cambios intermedios. El diseño debe aclarar qué representación necesita cada consumidor.
5. Mantén visibles los fallos de procesamiento
Recibir el evento y aplicarlo son dos hitos diferentes. Registra intentos, error clasificado, próxima actuación y estado final. Un evento atascado debe poder localizarse sin buscar mensajes entre varios servidores.
Limita los reintentos técnicos y deriva los errores que necesitan criterio a una cola de excepciones con acciones definidas. La repetición manual también debe respetar la identidad original y los efectos ya confirmados.
6. Prueba el efecto, además del código HTTP
| Prueba | Resultado que debe observarse |
|---|---|
| Firma inválida | El evento no entra en el flujo de negocio |
| Misma entrega simultánea | Una recepción lógica y efectos controlados |
| Reinicio después de confirmar | El trabajo aceptado sigue recuperable |
| Evento antiguo después del nuevo | El recurso no retrocede indebidamente |
| Fallo del destino | Queda evidencia y una vía de recuperación |
| Reproducción manual | Se respetan las garantías de idempotencia |
El entregable es un receptor cuya conducta se puede explicar cuando una entrega se repite, falta o llega tarde.
Si estás integrando APIs y servicios de backend, comparte con Nexeus Big Data el contrato del emisor y los efectos que produce cada evento. Esa relación permite definir una recuperación coherente antes de conectar la integración al proceso diario.