HMAC SHA-256 · Reintento · Idempotencia · Sandbox
Webhooks firmados para clientes enterprise
La forma en que su sistema recibe notificaciones del taller cuando algo cambia en una orden, en una entrega, en una factura, en una alerta de calidad o en una pieza de catálogo. Los webhooks se firman, se entregan con identificador único y se reintentan con backoff exponencial. La configuración se hace desde el portal del cliente con un endpoint HTTPS válido.
Cómo se firma un webhook
Cada webhook se firma con HMAC SHA-256. La firma se calcula sobre el cuerpo crudo de la petición — sin procesar — concatenado con el timestamp y con un identificador de evento único. La firma se entrega en el encabezado X-Corp-MX-Signature en formato hexadecimal. El cliente debe recalcular la firma con el secreto compartido y compararla con la firma recibida. Si las firmas no coinciden, el webhook se descarta.
Los encabezados que llegan con cada webhook son X-Corp-MX-Signature con la firma HMAC, X-Corp-MX-Timestamp con el timestamp UNIX en segundos del momento del envío, X-Corp-MX-Event-Id con el identificador único del evento — útil para idempotencia — y X-Corp-MX-Event-Type con el tipo de evento — order.created, order.approved, order.shipped, invoice.issued, entre otros.
Eventos de orden
Los eventos de orden cubren el ciclo completo. order.created cuando una orden queda registrada en el sistema tras la aprobación de la cotización. order.in_production cuando la orden arranca producción. order.stage_changed cuando una etapa avanza — corte, confección, personalización, empaque. order.quality_check cuando la orden pasa por inspección de calidad. order.shipped cuando la orden sale del taller con la guía del transportista. order.delivered cuando se confirma la entrega con acuse.
Para clientes con múltiples plantas, el evento order.stage_changed incluye el identificador de la planta. Para series con varias líneas, el evento order.line_completed se dispara cuando cada línea termina su producción, antes del consolidado. Esto permite que el cliente sepa cuándo una línea está lista sin esperar el consolidado de la orden completa.
Eventos de entrega
Los eventos de entrega cubren el ciclo logístico. shipment.created cuando se genera la guía con el transportista. shipment.in_transit cuando el envío entra en ruta con la primera actualización del transportista. shipment.out_for_delivery cuando el envío sale a reparto. shipment.delivered cuando se confirma la entrega con el nombre del receptor y, cuando aplica, la firma escaneada.
Para entregas con varias paradas — multisede, evento en venue — el evento shipment.stop_completed se dispara cuando se confirma la entrega en cada parada. La información incluye el domicilio, el responsable de recibo, el número de piezas entregadas y la firma cuando aplica. La trazabilidad se conserva durante el periodo de garantía del programa.
Eventos de factura y de calidad
Los eventos de factura cubren el ciclo de facturación. invoice.issued cuando la factura con CFDI 4.0 queda timbrada por el SAT y disponible para descarga. invoice.paid cuando se confirma el pago conforme al método de pago y al plazo acordados. invoice.canceled cuando se cancela la factura por el motivo declarado y se emite la refacturación cuando aplica.
Los eventos de calidad cubren no conformidades y acciones correctivas. quality.non_conformity_opened cuando se abre un 8D por una no conformidad detectada en producción o reportada por el cliente. quality.non_conformity_contained cuando se ejecuta la contención inmediata. quality.non_conformity_closed cuando se cierra el 8D con la acción correctiva verificada. El cliente puede suscribirse a todos los eventos de calidad o solo a los que afectan sus pedidos.
Reintentos y manejo de fallos
Cuando un webhook falla — endpoint devuelve un código de estado fuera del rango 2xx — el sistema reintenta automáticamente. La política de reintentos es de cinco intentos con backoff exponencial: a los sesenta segundos, a los cinco minutos, a los treinta minutos, a las dos horas y a las doce horas. Cuando el último intento falla, el evento queda en una cola de revisión manual y se notifica al responsable técnico del taller y del cliente.
El sistema nunca entrega un evento dos veces sin que el cliente lo sepa. Cada evento lleva un identificador único en el encabezado X-Corp-MX-Event-Id. El cliente debe almacenar el identificador y, al recibir un evento, verificar que no lo haya procesado antes. La idempotencia se mantiene por el identificador — el cliente descarta el segundo evento con el mismo identificador.
Configuración desde el portal del cliente
El cliente configura los webhooks desde el portal — disponible vía SSO — con un endpoint HTTPS válido. Para cada evento, el cliente selecciona si lo recibe o no. Para series con suscripción selectiva — solo eventos de orden, no de calidad — el cliente marca los eventos que requiere. La configuración se guarda y se aplica al instante sin necesidad de esperar una ventana de mantenimiento.
Para clientes con ambientes separados — sandbox y producción — se manejan dos endpoints independientes. El sandbox entrega eventos con datos ficticios para pruebas. La producción entrega eventos reales de los pedidos del cliente. El cliente puede probar la integración en el sandbox antes de mover el endpoint a producción con un solo cambio en el portal.
Buenas prácticas para el cliente
Recomendamos cuatro prácticas. Primero, validar la firma HMAC SHA-256 antes de procesar el cuerpo — si la firma no coincide, descartar. Segundo, validar el timestamp con tolerancia de cinco minutos — si el evento es más viejo que cinco minutos, descartar para evitar ataques de replay. Tercero, mantener idempotencia por el identificador del evento — almacenar el identificador en una tabla con TTL de veinticuatro horas.
Cuarto, responder rápido — el endpoint debe devolver un código 2xx en menos de cinco segundos. Si el procesamiento interno toma más tiempo, el cliente debe devolver el 2xx inmediatamente y procesar el webhook en segundo una con un job asincrónico. Cuando el endpoint devuelve un 5xx o un timeout, el sistema lo trata como fallo y dispara el reintento.
Configure sus webhooks con Corp-Merch.MX
Si su equipo técnico requiere la integración por webhooks con su stack de operaciones, platiquemos. Les entregamos el endpoint del sandbox, el secreto de firma y la documentación completa en formato del cliente.
Los webhooks se entregan a clientes con programa vigente y contrato de uso firmado. La documentación puede actualizarse sin previo aviso; las versiones mayores se comunican con treinta días de anticipación. Corp-Merch.MX es un taller mexicano de producción de merch corporativo; operamos de manera independiente.