Redacción: 4SYSTEMPublicado el Actualizado el
7 min de lectura
Cómo separar recepción y procesamiento de negocio, resistir los duplicados y recuperar eventos tras una caída sin repetir las acciones.
Para que los webhooks ecommerce sean fiables, verifica la firma, registra la entrega de forma duradera antes de confirmar su recepción y protege las acciones contra duplicados. Un webhook es una notificación enviada a tu aplicación; recibirla no demuestra que el pedido se haya procesado. Shopify documenta las entregas repetidas y Stripe aclara que el orden de llegada de los eventos no está garantizado.[1][3] Diseña, por tanto, el circuito para soportar repeticiones, retrasos e interrupciones.
Distinguir entrega, evento y acción de negocio
La entrega es la solicitud recibida. El evento es lo que ha ocurrido en la plataforma. La acción de negocio es lo que tu sistema decide hacer: actualizar un estado, crear una tarea de preparación o transmitir una solicitud. Estas identidades no se confunden. En Shopify, la documentación distingue X-Shopify-Webhook-Id para deduplicar entregas y X-Shopify-Event-Id para correlacionar varias entregas procedentes de una misma acción del comerciante.[1]
Define también qué sistema es la referencia para cada dato. Una notificación antigua no debe sobrescribir ciegamente un estado más reciente. Según la necesidad, el procesamiento puede volver a consultar el objeto actual en la plataforma y decidir si la acción sigue siendo pertinente. Los identificadores, el ámbito de la cuenta y la versión del formato deben figurar en el contrato de integración. Esta precisión es más útil que una promesa general deautomatización de marketing.
Asignar una responsabilidad a cada etapa
Una arquitectura clara separa la recepción rápida de la solicitud del trabajo que puede durar. Shopify recomienda utilizar una cola para absorber picos; Stripe también recomienda el procesamiento asíncrono.[1][3] La siguiente tabla describe responsabilidades de diseño, no una garantía que una biblioteca proporcione automáticamente.
| Etapa del webhook | Responsabilidad | Prueba técnica que conservar |
|---|---|---|
| Recepción de un webhook | Verificar el origen y el formato esperado | Resultado de validación e identificador |
| Registro | Conservar una tarea duradera y su estado | Identificador de tarea y fecha de recepción |
| Procesamiento | Aplicar una acción sin efectos repetidos | Clave de negocio y resultado de la operación |
| Recuperación tras un incidente | Reexaminar las tareas incompletas | Historial de intentos y motivo del fallo |
Separar recepción y procesamiento
La firma debe verificarse sobre el cuerpo original, antes de que una transformación lo modifique. Shopify y Stripe lo especifican en sus respectivas documentaciones.[1][3] Utiliza las herramientas oficiales adecuadas a tu entorno y mantén los secretos fuera de los registros. Una firma válida no elimina los controles de duplicados ni las reglas de negocio.
- Recibir la solicitud, preservar el cuerpo original y verificar la firma según el contrato exacto del proveedor. Rechazar una validación incorrecta sin iniciar acciones de negocio.
- Construir una identidad persistente que incluya el proveedor, la cuenta afectada y el identificador de entrega o evento adecuado.
- Registrar la tarea con una restricción de unicidad. Una simple búsqueda seguida de una inserción separada permite una condición de carrera entre solicitudes concurrentes.
- Confirmar la recepción solo después de ese registro duradero. Si el almacenamiento falla, no declarar aceptada una tarea que podría perderse.
- Encargar el procesamiento a un ejecutor distinto, con estados explícitos, reserva del trabajo y protección de la acción de negocio contra repeticiones.
- Conservar el resultado y prever la recuperación de tareas fallidas o abandonadas, sin volver a ejecutar indiscriminadamente todas las acciones completadas.
Deduplicar una entrega no basta si el proceso cae después de la acción externa pero antes de registrarla localmente. Para ese caso, prevé una clave de idempotencia aceptada por el sistema destinatario o una comprobación del efecto ya producido. Aquí, idempotencia significa que una repetición no crea un efecto de negocio adicional. Una transacción local, por sí sola, no puede abarcar una acción remota independiente.
Ejemplo ficticio: una preparación creada una sola vez
Ejemplo completamente ficticio: un evento llamado evt-demo corresponde al pedido CMD-DEMO. La aplicación recibe una entrega, la conserva y crea una tarea de preparación. Llega otra entrega después de un corte de red. El circuito reconoce la identidad ya conservada y no crea otra tarea de negocio. Puede confirmar la recepción porque el trabajo inicial sigue registrado de forma duradera, aunque todavía no haya terminado.
Si la herramienta logística aceptó la preparación antes de una caída del ejecutor, la recuperación comprueba la clave de negocio asociada a CMD-DEMO en vez de enviar otra creación sin control. Los estados deben distinguir «recibido», «en curso», «completado» y «por recuperar». Este ejemplo no afirma ningún comportamiento de una aplicación real: cada sistema destinatario debe evaluarse respecto a esta protección.
Preparar incidentes y conciliación
Los reintentos del proveedor no sustituyen tu procedimiento de recuperación. Shopify explica cómo volver a importar datos ausentes tras una indisponibilidad y comprobar las suscripciones afectadas.[2] Define una ventana de conciliación, los datos que consultar, las autorizaciones de recuperación y el control final. Una notificación de venta no debe convertirse automáticamente en prueba de ingresos en tu plan de medición de eventos.
- Prever una prueba con entregas idénticas y concurrentes: se espera una sola acción de negocio.
- Prever una interrupción después del almacenamiento y otra después de la acción externa para comprobar ambas vías de recuperación.
- Prever eventos retrasados o desordenados y comprobar que el estado final siga siendo coherente con la fuente.
- Supervisar la antigüedad de las tareas, los fallos y los resultados de conciliación, con registros limitados a los datos necesarios.
Preguntas frecuentes
¿Una respuesta de éxito significa que todo ha terminado?
No. Puede significar que la notificación se ha aceptado de forma duradera para su procesamiento. El estado de negocio debe seguirse por separado. Esta distinción permite una recepción rápida sin afirmar que la operación logística o contable ya ha concluido. Documenta con precisión a qué compromete tu respuesta.
¿Se puede utilizar el mismo identificador en todas partes?
No sin comprobar su ámbito. Un identificador puede designar una entrega, un evento o un objeto de negocio. Shopify distingue, en particular, los identificadores de entrega y los de correlación de eventos. La elección depende del efecto que proteger y del alcance de la integración, no solo del nombre de la cabecera.[1]
¿La cola garantiza el procesamiento exactamente una vez?
No lo supongas. El circuito debe soportar la recuperación y proteger el efecto final, incluso después de un fallo entre sistemas. Comprueba por separado almacenamiento, concurrencia e idempotencia del destinatario. Una recepción sin errores no demuestra esta propiedad de extremo a extremo.
Describir las garantías antes de conectar herramientas
Los webhooks ecommerce fiables necesitan una identidad clara, almacenamiento duradero y acciones verificables después de un incidente. Empieza por el escenario en el que una repetición sería costosa y define después las pruebas de recepción y éxito. Para delimitar los intercambios entre tienda y herramientas de negocio, los servicios de 4SYSTEM permiten hablar del contrato de integración y de la validación, sin presentar un ejemplo didáctico como conector universal.