¿Cómo evitar pedidos duplicados cuando un webhook de pago llega dos veces?
La creación del pedido no debe ejecutarse otra vez cuando se vuelve a entregar el mismo webhook de pago. Use el identificador de evento del proveedor junto con una clave de negocio única y…
¿Qué contiene este artículo?
Respuesta breve
La creación del pedido no debe ejecutarse otra vez cuando se vuelve a entregar el mismo webhook de pago. Use el identificador de evento del proveedor junto con una clave de negocio única y guarde el estado de procesamiento de forma atómica en la base de datos. Responder con éxito al webhook y completar realmente un pedido son fases distintas.
El identificador de evento y el de pedido son protecciones distintas
El identificador del proveedor permite reconocer la entrega repetida de una notificación. Sin embargo, pueden llegar distintos tipos de evento para un mismo pago. Comprobar solo si el evento llegó antes puede no bastar. La asociación del pedido con el pago y la clave de negocio también necesita una regla de unicidad. Diseñe la entrega repetida como un escenario de fallo legítimo y esperado.
Consultar primero la base de datos e insertar después puede provocar una condición de carrera entre dos solicitudes simultáneas. Proteja el procesamiento con una restricción de unicidad y un ámbito transaccional adecuado. Distinga los estados «recibido», «en proceso», «completado» y «error». La existencia de un registro sin terminar no significa que la operación haya concluido correctamente.
Verificación de firma y cola segura
Aplique el método de verificación de firma del proveedor antes de las reglas de negocio. Consulte en su documentación oficial el formato de cuerpo necesario. No ponga una solicitud inválida en la cola como evento de pago normal. Tras registrar de forma duradera un evento válido, las tareas largas pueden ejecutarse en una cola controlada. No guarde detalles sensibles del pago en los registros técnicos.
El comportamiento de entrega documentado por Stripe sirve para integraciones Stripe; no suponga iguales los plazos de reintento o formatos de firma de otros proveedores. La propuesta debe indicar proveedor, tipos de evento, reglas de reintento y responsable de las tareas fallidas. Las solicitudes API idempotentes son una capa distinta de la protección del procesamiento de webhooks.
La conciliación es tan importante como evitar pedidos duplicados
Pruebe la entrega del mismo evento dos veces, simultáneamente y después de interrumpir el procesamiento. Abra una tarea de conciliación si el pago termina sin crear pedido. La pantalla operativa debe vincular pago y pedido y mostrar qué cambiará al reprocesar. El objetivo no es solo evitar duplicados, sino detectar pedidos perdidos.
Lista de verificación de implementación
- ¿Se verifica la firma del webhook?
- ¿Hay una restricción de unicidad en el identificador de evento?
- ¿Se protege por separado la clave de pedido asociada al pago?
- ¿Puede reprocesarse una operación interrumpida?
- ¿Es visible la conciliación pago–pedido?
Preguntas frecuentes
¿Una respuesta HTTP exitosa indica que terminó el pedido?
No. La confirmación de recepción del evento y la finalización del flujo de negocio son registros distintos.
¿Todos los proveedores tienen la misma regla de reintento?
No. Deben aplicarse el contrato y la documentación oficiales del proveedor seleccionado.
Alcance y límites
Este enfoque no sustituye las pruebas de integración específicas del proveedor. Valide los pagos y reembolsos en su entorno de pruebas antes de pasar a producción.
Fuentes y actualidad
Revisión de fuentes: 7 de octubre de 2026. Las versiones de los documentos enlazados y las condiciones de los proveedores pueden cambiar. Compruebe la versión actual de la fuente pertinente antes de implementar.