Webhooks para pedidos y facturas en España
Suscríbete a eventos order.*, invoice.* (vía FACe/SII (AEAT)) y shipment.*. Firmados HMAC-SHA256, retry 6×, protegidos contra replay con X-Corp-Timestamp.
Catálogo de eventos
order.accepted, order.confirmed, order.in_production, order.shipped, order.delivered, order.cancelled, invoice.issued, invoice.paid, invoice.credit_note (todos vía FACe/SII (AEAT) para IVA 21% en España), shipment.label_created, shipment.eta_changed, catalog.updated. Cada evento incluye event_id, event_type, occurred_at, data{…}.
Firma y verificación
Cabecera X-Corp-Signature: t=
Reintentos y dead-letter
En respuesta no-2xx: retry a 1m, 5m, 15m, 1h, 6h, 24h (seis intentos en ~31 horas). Agotado, suscripción se pausa y alerta email al contacto ops registrado. Eventos dead-letter vía GET /v1/webhooks/{id}/dead_letter por 30 días; replay manual vía POST /v1/webhooks/{id}/replay/{event_id}.
FAQ
¿Qué método HTTP y content-type?
POST application/json. Siempre UTF-8. Enviamos Content-Length y Content-Encoding: identity (sin gzip por defecto).
¿Puedo tener múltiples endpoints?
Sí — hasta 10 suscripciones activas por cuenta, cada una puede filtrar por prefijo event_type (ej. invoice.*). Útil para separar tráfico ERP y observabilidad.
¿Y si mi endpoint está brevemente indisponible?
Los reintentos cubren ~31 horas; outages breves absorbidos transparentemente. Para outages más largos, replay de eventos dead-letter al recuperar.
¿Los eventos están ordenados?
Eventos para el mismo recurso (order_id) entregados en orden causal best-effort (sin garantía). Usa occurred_at + event_id para reconstruir orden en cliente si es necesario.
¿Cómo roto el secret de firma?
POST /v1/webhooks/{id}/rotate_secret — devuelve el nuevo secret; el anterior sigue válido 24 horas como periodo de gracia.