ES Webhooks seguros en ecommerce: firmas, reintentos e idempotencia
Un webhook fiable no se limita a recibir un JSON y ejecutar una acción. Debe comprobar que el mensaje procede del proveedor esperado, resistir reintentos y duplicados, responder con rapidez y dejar una trazabilidad suficiente para recuperar eventos sin repetir cobros, pedidos o envíos. En ecommerce, estos detalles separan una integración estable de una incidencia difícil de reconstruir.
Los webhooks permiten que una pasarela de pago, un ERP, un marketplace o un operador logístico avise a la tienda cuando cambia algo. El mensaje llega de forma asíncrona: no hay una persona esperando delante de la pantalla y el emisor puede repetirlo si no recibe la respuesta prevista. Por eso el receptor debe diseñarse para una entrega «al menos una vez», incluso cuando cada proveedor describa sus propias reglas.
La URL secreta no autentica al emisor
Ocultar la ruta del webhook reduce ruido accidental, pero no demuestra quién envió la petición. Una URL puede aparecer en registros, herramientas de soporte, capturas o configuraciones compartidas. El endpoint debe estar disponible solo por HTTPS y validar el mecanismo que documenta el proveedor: normalmente una firma calculada sobre el cuerpo del mensaje, acompañada de un identificador, una fecha u otros componentes.
GitHub, por ejemplo, firma cada entrega con un secreto y envía el resultado en X-Hub-Signature-256. Stripe utiliza su propio encabezado y recomienda sus bibliotecas oficiales para reconstruir y verificar la firma. No conviene inventar un algoritmo común para todos: nombre del encabezado, formato, contenido firmado, codificación y tolerancia temporal dependen del contrato concreto.
El RFC 9421 define un marco general para firmar componentes de mensajes HTTP. Es una referencia útil para entender que la seguridad depende de reconstruir exactamente la misma base de firma y cubrir los componentes adecuados. No significa que un proveedor concreto implemente ese estándar: siempre manda su documentación y su versión de API.
Verifica la firma antes de transformar el cuerpo
Uno de los fallos más frecuentes aparece cuando el framework convierte primero el JSON en un objeto, cambia espacios, escapes o codificación, y después intenta verificar la firma. Stripe indica expresamente que necesita el cuerpo original sin modificaciones. GitHub también recomienda comprobar que proxy, balanceador y aplicación no alteran payload ni encabezados antes de la validación.
La secuencia segura empieza leyendo los bytes originales dentro de un límite razonable, obteniendo la firma del encabezado esperado y aplicando el secreto correspondiente al entorno y al endpoint. La comparación debe hacerse con una función resistente a diferencias de tiempo, no con una igualdad de cadenas corriente. Solo después de validar se analiza el JSON y se comprueba que contiene un tipo de evento permitido y la estructura necesaria.
- separa secretos de pruebas y producción, y no los guardes en el repositorio ni en el webroot;
- rechaza métodos y tipos de contenido no previstos;
- limita el tamaño del cuerpo y el tiempo de lectura;
- rota secretos con una ventana controlada cuando el proveedor lo admita;
- no incluyas el payload completo ni datos personales en registros de error por defecto.
OWASP recomienda HTTPS para servicios REST, una lista permitida de métodos y validación del tipo de contenido. Estas medidas no sustituyen la firma, pero reducen superficie de ataque y evitan que el receptor interprete formatos inesperados.
Un mensaje legítimo también puede llegar dos veces
Una firma válida confirma que el mensaje encaja con el mecanismo del proveedor; no asegura que sea la primera entrega. Si el endpoint tarda demasiado, se corta la conexión o devuelve un estado no aceptado, el emisor puede reintentarlo. También puede haber reenvíos manuales. Stripe advierte de eventos duplicados y recomienda registrar los identificadores ya procesados.
La primera barrera es una clave única de entrega o evento. Antes de ejecutar la acción, el sistema intenta registrar esa clave de manera atómica. Si ya existe, devuelve una respuesta coherente sin volver a modificar el pedido. El periodo de conservación debe cubrir como mínimo la ventana real de reintentos y reenvíos del proveedor, teniendo en cuenta requisitos operativos y de protección de datos.
La segunda barrera es la idempotencia de la operación de negocio. Marcar un pedido como pagado puede expresarse como una transición desde un estado permitido, no como «sumar un pago» cada vez que llega el evento. Crear un envío puede apoyarse en una referencia única. Enviar un correo debería registrar qué notificación se produjo. Así, un fallo en la tabla de eventos no convierte automáticamente el reintento en una acción duplicada.
No des por hecho el orden de entrega
En sistemas distribuidos, un evento posterior puede llegar antes que otro anterior. Stripe declara que no garantiza el orden. El consumidor debe decidir qué versión del objeto es vigente, consultar al proveedor cuando falte información o guardar temporalmente un evento hasta disponer de sus dependencias. Ordenar solo por la hora de recepción del servidor puede producir conclusiones falsas.
Para pedidos y pagos conviene definir una máquina de estados: qué transiciones son válidas, cuáles se ignoran, cuáles necesitan conciliación y cuáles deben generar una alerta. Si un mensaje «pago confirmado» llega cuando el pedido todavía no existe localmente, la aplicación no debería descartarlo sin rastro ni crear datos parciales a ciegas.
Responde rápido y procesa el trabajo fuera de la petición
El endpoint debería verificar, validar, registrar y colocar el evento en una cola antes de devolver un 2xx. Las tareas lentas —actualizar varios sistemas, generar documentos, llamar a logística o enviar mensajes— se ejecutan después. GitHub exige una respuesta satisfactoria dentro de diez segundos; Stripe también recomienda responder antes de la lógica compleja. El límite exacto cambia según el proveedor, pero el patrón arquitectónico es el mismo.
La respuesta rápida solo es correcta cuando el evento ya está guardado de forma recuperable. Contestar éxito y confiar en una tarea en memoria puede perderlo si el proceso se reinicia. Por el contrario, procesar todo antes de responder aumenta los timeouts y reintentos. La cola debe incluir reintentos internos con espera progresiva, número máximo de intentos y una zona de incidencias para mensajes que requieren revisión.
Observabilidad sin convertir los logs en otro riesgo
Un panel útil muestra entregas recibidas, firmas rechazadas, duplicados, tiempo hasta la respuesta, retraso de cola, errores por tipo y mensajes pendientes. Cada registro necesita identificadores técnicos que permitan seguir el recorrido sin almacenar innecesariamente direcciones, nombres, tokens o cuerpos completos.
Las alertas deben distinguir un ataque o una mala configuración de una caída del sistema interno. Un aumento de firmas inválidas puede indicar un secreto equivocado o tráfico hostil; una cola que crece con firmas válidas apunta a capacidad o dependencias. También conviene documentar cómo reenviar un evento, cómo conciliar el estado con el proveedor y quién decide una corrección manual.
Pruebas mínimas antes de abrir producción
- acepta una entrega de prueba con firma válida y conserva el cuerpo original;
- rechaza una firma ausente, alterada, antigua cuando aplique o calculada con otro secreto;
- envía dos veces el mismo identificador y confirma una sola acción de negocio;
- cambia el orden de dos eventos relacionados y revisa el estado final;
- simula una caída del trabajador y comprueba que la cola recupera el mensaje;
- mide la respuesta del endpoint bajo ráfagas y verifica alertas y conciliación.
En proyectos de desarrollo web a medida, este contrato puede definirse junto con los estados de pedido y las integraciones. Una tienda ya operativa puede revisar sus receptores mediante soporte técnico y mantenimiento evolutivo. Para delimitar proveedores, riesgos y accesos, se puede iniciar una valoración desde contacto.
Preguntas frecuentes sobre webhooks y VOWE
¿Puede VOWE revisar los webhooks de una tienda online o aplicación?
Sí. Dentro del desarrollo web a medida y el soporte técnico, VOWE puede inventariar las integraciones, revisar la validación de firmas, los reintentos, la deduplicación, las colas y los registros, y preparar pruebas controladas. El alcance depende de la plataforma, los proveedores, el alojamiento y los accesos autorizados disponibles.
¿Una firma válida evita por sí sola los pedidos o cobros duplicados?
No. La firma ayuda a comprobar el origen y la integridad del mensaje, pero un proveedor puede volver a entregar un evento legítimo. El receptor también necesita identificar eventos ya procesados y hacer idempotentes las operaciones de negocio para que un reintento no repita una acción irreversible.
¿Qué información hace falta para valorar una integración con webhooks?
Para una primera valoración hacen falta los proveedores y tipos de evento, la documentación de firma y reintentos, el flujo de negocio que activa cada mensaje, los tiempos de respuesta actuales, los registros disponibles y el procedimiento de prueba. No es necesario enviar secretos, claves ni datos personales mediante el formulario de contacto.
Fuentes y límites de esta guía
La guía sintetiza las recomendaciones de Stripe sobre firmas, duplicados, reintentos, orden y colas, la documentación de GitHub para validar entregas y responder a webhooks, la REST Security Cheat Sheet de OWASP y el estándar RFC 9421 sobre firmas de mensajes HTTP. Cada proveedor tiene un contrato distinto; hay que seguir su documentación vigente y probar el flujo completo en el entorno correspondiente.
