Ir al contenido principal

Referencia de webhooks

Referencia de webhooks Fabrixa - eventos de estado de pedido, cargas útiles firmadas, integración en tiempo real
DESARROLLADORES - REFERENCIA DE WEBHOOKS

Ordenar eventos del ciclo de vida, firmados y a prueba de reintentos.

Los webhooks se disparan en cada transición de estado del pedido: recibido, impreso, enviado, fallido. JSON sobre HTTPS, HMAC-SHA256 firmado para verificación, cola de reintentos con exponencial de hasta 24 horas. Referencia de eventos, ejemplos de código de verificación de firma y política de reintento / letra muerta a continuación.

HMAC-SHA256 SIGNED - AT-LEAST-ONCE - 24h RETRY - DEAD-LETTER QUEUE

TIPOS DE EVENTOS

Cinco eventos del ciclo de vida del pedido.

Suscribirse a cualquier subconjunto en el PUT /v1/cuenta/webhook punto final. La mayoría de las integraciones se suscriben a los cinco.

Evento Se dispara cuando Acción típica
pedido.recibidoFabrixa aceptó el pedido y asignó un orden_id. Ack a los pocos segundos de POST.Actualizar el estado del pedido interno a "en producción"; superficie al cliente final.
pedido.impresoPaso de impresión reactiva completado. La prenda pasa a la fase de corte y costura. Hito de mitad de producción.Opcional - algunos equipos lo utilizan para los correos electrónicos de "su pedido se está realizando".
pedido.expedidoCalidad comprobada, empaquetado, entregado al transportista. Número de seguimiento emitido.Actualizar el estado del pedido a "enviado"; activar la notificación de envío al cliente final con la URL de seguimiento.
pedido.entregadoEntrega confirmada por el transportista en la dirección del destinatario.Activar flujos posteriores a la compra: solicitud de revisión, venta de productos relacionados, etc.
orden.fallidaEl pedido no puede completarse - obra de arte no localizable, dirección del destinatario no válida, tejido agotado durante un largo periodo.Abrir ticket / notificar a operaciones. La carga útil incluye código.error para la lógica de encendido.
FORMA DE CARGA

El mismo sobre, datos específicos del evento.

Envolvente común (evento, order_id, order_ref, timestamp) más un evento específico datos objeto. Consumir primero el sobre; encender evento para la forma de los datos.

pedido.expedido
# order.dispatched payload - POST a la URL de su webhook

POST /su-webhook-punto-final
Tipo de contenido: application/json
Evento X-Fabrixa: pedido.expedido
X-Fabrixa-Firma: t=1715173928,v1=ab3c4...
X-Fabrixa-Id-Entrega: del_94kQ7r2L

{
  "evento":        "pedido.expedido",
  "order_id":     "ord_8e6f4b2a",
  "pedido_ref":    "shopify-1042",
  "timestamp":    "2026-05-15T11:32:08Z",
  "production_hub": "PT",
  "datos": {
    "seguimiento": {
      "transportista":         "DHL",
      "tracking_number": "JJD0123456789",
      "tracking_url":    "https://dhl.com/track/JJD0123456789",
      "entrega_estimada": "2026-05-19"
    },
    "destinatario": {
      "nombre":    "Lena Costa",
      "ciudad":    "Oporto",
      "país": "PT"
    }
  }
}
VERIFICACIÓN DE FIRMAS

HMAC-SHA256 sobre (timestamp + raw body).

Verifique la firma antes de procesarla. Utilice la función cuerpo de la solicitud sin procesar - no un objeto JSON re-serializado - o el HMAC no coincidirá. El secreto de firma se emite una vez al configurar la URL del webhook; gírelo a través del panel de control.

verificar-firma.js
// Ejemplo Node.js / Express
const cripto = requiere("cripto");

app.Correo electrónico:("/webhook", Expreso.en bruto({ tipo: "application/json" }), (req, res) => {
  const firma = req.headers["x-fabrixa-firma"];
  const [tPart, v1Part] = firma.dividir(",");
  const timestamp = tPart.dividir("=")[1];
  const recibido = v1Part.dividir("=")[1];

  // Rechazar eventos de más de 5 minutos (protección contra repeticiones)
  si (Matemáticas.abs(Fecha.ahora() / 1000 - timestamp) > 300) devolver res.estado(400).fin();

  const payload = `${timestamp}.${req.body.toString()}`;
  const esperado = crypto
    .crearHmac("sha256", process.env.FABRIXA_WEBHOOK_SECRET)
    .actualización(carga útil)
    .resumen("hex");

  si (!crypto.timingSafeEqual(Buffer.de(recibido), Buffer.de(esperado))) {
    devolver res.estado(401).fin();
  }

  // Firma válida - procesa el evento
  const evento = JSON.analizar(req.body);
  handleEvent(evento);
  res.estado(200).fin();
});

Las muestras equivalentes para Python (Flask), PHP, Ruby y Go se encuentran en la carpeta de scripts de la colección Postman. timingSafeEqual importa - no uses la igualdad de cadenas, es vulnerable a ataques de sincronización.

POLÍTICA DE DEVOLUCIÓN

Retroceso exponencial de hasta 24 horas.

Los webhooks se entregan al menos una vez. Si su punto final devuelve 5xx o se agota el tiempo de espera (tiempo de espera de 10 segundos), volvemos a intentarlo con un programa exponencial durante un máximo de 24 horas. Tras 24 horas de fallo, el evento se coloca en una cola de espera que puede reproducirse manualmente.

INMEDIATO

Entrega inicial + reintento 1

Primera entrega en el evento. Si 5xx o timeout, reintentar 30 segundos después.

BACKOFF

Reintentos 2-8, exponencial

60s → 5min → 30min → 2h → 6h → 12h → 24h. Cada reintento espera más tiempo.

CARTA MUERTA

Tras 24h de fallo

Evento movido a cola de muertos. Reproducir manualmente a través del panel o POST /v1/webhooks/replay/:delivery_id.

EVENTO ORDER.FAILED

Motivos de error estructurados para la lógica de conexión.

El acontecimiento más importante desde el punto de vista operativo. La carga útil incluye un código.error cadena - seguro para activar el enrutamiento automatizado, la creación de tickets o la mensajería al cliente final.

orden.fallida
{
  "evento":     "pedido.fallido",
  "order_id":  "ord_8e6f4b2a",
  "pedido_ref": "shopify-1042",
  "timestamp": "2026-05-13T09:14:22Z",
  "datos": {
    "error": {
      "código":    "obra_inaccesible",
      "mensaje": "GET on artwork_url failed (timeout 30s) after 3 attempts",
      "reintentable": verdadero,
      "contexto": {
        "url_obra_de_arte": "https://cdn.yourbrand.com/art/drop-001.png"
      }
    }
  }
}

# Valores comunes del código de error:
# artwork_unreachable - la URL de tu obra no ha respondido
# artwork_invalid_format - no se ha podido analizar el archivo (pruebe con PNG / PDF vectorial)
# artwork_resolution_low - DPI demasiado baja para el producto elegido
# address_invalid - la dirección del destinatario no se ha validado
# fabric_unavailable - base de tela agotada desde hace >7 días
# payment_method_failed - facturación en archivo rechazada
# compliance_flag - orden marcada por la revisión de conformidad
PRUEBAS

Desencadenar eventos de muestra sin órdenes reales.

POST /v1/webhooks/prueba envía un evento sintético de cualquier tipo a su URL webhook registrada. Útil para probar su manejador antes de realizar pedidos reales, o para verificar un nuevo punto final después de un despliegue.

Los webhooks del sandbox entregan a su URL del sandbox. Utilice una herramienta de tunelización (ngrok, Cloudflare Tunnel) para apuntar los webhooks de sandbox a localhost durante el desarrollo.

POST /v1/webhooks/prueba
rizo -X POST $BASE_URL/v1/webhooks/test \
  -H "Autorización: Portador $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "evento": "pedido.expedido",
    "sample_order_id": "muestra"
  }'

# 200 OK
{
  "delivery_id": "del_test_94kQ",
  "posted_to":   "https://your-tunnel.ngrok.io/webhook",
  "status":      "en cola"
}
Configurar webhooks Fabrixa: eventos de pedidos en tiempo real para su plataforma
REGISTRE SU WEBHOOK

Establezca la URL una vez. Nosotros nos encargamos de la entrega.

Una URL de webhook por cuenta, todos los tipos de eventos se disparan a ella. Filtro en el evento en su controlador. Configurar a través de la guía de integración.

Carrito (0 artículos)

Crea tu cuenta