Cada evento. Cada payload. Firmado.
Fabrixa envía eventos de pedidos a su endpoint en tiempo real. Su servidor expone un endpoint POST público; nosotros enviamos el cuerpo completo del pedido con una firma HMAC-SHA256 y el topic del evento en los encabezados. Verifique la firma, devuelva un código de estado 200 rápidamente y procese el pedido de forma asíncrona.
Hay tres encabezados que identifican y verifican la solicitud.
Cada solicitud POST de webhook incluye los mismos tres encabezados. Utilice x-webhook-topic para redirigir el evento y x-webhook-signature para comprobarlo antes de confiar en el cuerpo del mensaje.
content-type es siempre application/json. x-webhook-signature es el HMAC-SHA256 codificado en base64 del cuerpo sin procesar. x-webhook-topic es el nombre del evento.
{
"content-type": "application/json",
"x-webhook-topic": "order.updated",
"x-webhook-signature": "YmEwNjBhMGMy...MAxMw=="
}
Dos topics por ahora.
Cada webhook se activa mediante un valor concreto de x-webhook-topic en cuestión. Ambos contienen el objeto de pedido completo, por lo que un único handler puede bifurcar según el topic.
Se ha realizado un nuevo pedido.
Se activa cuando se crea un pedido en Fabrixa, ya sea a través de una solicitud de API o directamente en la plataforma.
Se produce un cambio en un pedido ya existente.
Se activa cuando cambian los detalles del pedido; por ejemplo, cuando cambia el estado del pedido o el estado de fulfilment.
Qué pueden indicar los campos de estado.
Lel payload transporta el pedido status además de un fulfillment_status. Bifurque según estos valores para gestionar el estado de su propio pedido.
- Completed — enviado o recogido y con el recibo confirmado.
- Canceled — El pago se ha cancelado; la transacción no se ha completado.
- On hold — El pedido está bloqueado temporalmente.
- Imported — El pedido se ha importado a la plataforma.
- Unfulfilled — aún no está preparado ni enviado.
- Partially fulfilled — algunos artículos ya se han tramitado o enviado, otros están pendientes.
- Scheduled — planificados y programados para su procesamiento.
- Rejected — La solicitud de tramitación ha sido denegada.
- Fulfilled — totalmente procesados y entregados o puestos a disposición.
Cómo es el cuerpo.
El payload completo de order.updated tal y como se documenta en la referencia de la API: el pedido, sus estados y las filas con los detalles de variante, producto y source.
{
"id": 23069,
"number": "1250211835",
"comments": null,
"is_archived": false,
"status": "imported",
"fulfillment_status": "unfulfilled",
"purchased_at": "2025-04-17T16:17:21.000000Z",
"created_at": "2025-04-17T16:17:23.000000Z",
"updated_at": "2025-04-18T07:43:52.000000Z",
"rows": [
{
"id": 27954,
"quantity": 1,
"client_barcode": "1250211835",
"fulfillment_status": "unfulfilled",
"variant": {
"id": 293457,
"name": "Sherpa fleece deken",
"subtitle": "100x150",
"SKU": "SFD787231",
"product": {
"id": 5319, "name": "Sherpa fleece deken", "subtitle": "Sherpa fleece deken"
}
},
"sources": [
{
"type": "print",
"url": "https://storage.googleapis.com/fabrixa-api/…/120002795400.pdf",
"properties": { "fill_style": "contain" }
}
]
}
]
}
Vuelva a calcular el HMAC, compárelo y, a continuación, considera fiable el cuerpo del mensaje.
Vuelve a calcular el HMAC-SHA256 de lel payload sin procesar de la solicitud con su clave secreta, codifíquela en base64 y compárela con x-webhook-signature. Utilice siempre una comparación de tiempo constante (hash_equals) para evitar ataques de temporización.
$payload = file_get_contents('php://input'); $secret = 'your-secret-key'; $expected = base64_encode( hash_hmac('sha256', $payload, $secret, true) ); $received = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? ''; // constant-time compare if (!hash_equals($expected, $received)) { http_response_code(403); exit('Invalid signature'); }
public function handle(Request $request)
{
$secret = 'your-secret-key';
$payload = $request->getContent();
$expected = base64_encode(
hash_hmac('sha256', $payload, $secret, true)
);
$received = $request->header('x-webhook-signature');
if (!hash_equals($expected, $received)) {
abort(403, 'Invalid signature');
}
// Continue processing…
}
Los reintentos y la respuesta que esperamos.
Hasta 10 intentos; después, se desactiva
Cualquiera 2xx una respuesta (p. ej., 200) se considera un éxito, al igual que un 301 o 302 redirigir. Cualquiera 4xx, 5xx o si se agota el tiempo de espera, se inicia un nuevo intento —hasta un máximo de 10 en total—. Tras el décimo fallo, el webhook se desactiva.
Devuelva 200 rápido y procese de forma asíncrona
Confirmar con 200 OK lo antes posible y, a continuación, gestionar lel payload de forma asíncrona mediante una tarea en segundo plano o una cola. Un endpoint lento puede considerarse un error, aunque finalmente se complete con éxito.
Webhooks, respondido
¿Cómo puedo verificar la firma de un webhook Fabrixa?
Vuelve a calcular el HMAC-SHA256 del cuerpo de la solicitud sin procesar utilizando su clave secreta, codifica el resultado en base64 y compáralo con el encabezado «x-webhook-signature» mediante una comparación de tiempo constante, como «hash_equals». Fabrixa ofrece ejemplos prácticos en PHP sin procesar y en Laravel, y cualquier discrepancia debe rechazarse antes de que se procese lel payload.
¿Qué eventos de webhook envía Fabrixa?
Fabrixa envía dos eventos, identificados por el encabezado «x-webhook-topic»: «order.created», que se activa cuando se realiza un pedido a través de API o directamente en la plataforma, y «order.updated», que se activa cuando cambia el estado del pedido o el estado de su tramitación. Ambos incluyen el objeto de pedido completo, por lo que un único gestor puede encargarse de este tema.
¿Cuántas veces vuelve a intentar Fabrixa un webhook que ha fallado?
Fabrixa reintenta el envío de un webhook hasta 10 veces cuando la respuesta no es un 2xx, 301 o 302. Cualquier código 4xx, 5xx o tiempo de espera agotado se considera un fallo y desencadena un nuevo intento; tras el décimo intento fallido, el webhook se desactiva, por lo que el endpoint debe devolver un 200 rápidamente y procesar lel payload de forma asíncrona.
¿Qué encabezados incluye una solicitud de webhook Fabrixa?
Cada solicitud POST de webhook incluye tres encabezados: «content-type», siempre «application/json»; «x-webhook-topic», que designa el evento (por ejemplo, «order.updated»); y «x-webhook-signature», la firma HMAC-SHA256 codificada en Base64 del cuerpo sin procesar. Utilice el «topic» para enrutar el evento y la firma para verificarlo antes de confiar en lel payload.
¿Qué estados de los pedidos aparecen en lel payload de un webhook de Fabrixa?
Lel payload incluye un campo «status» con cuatro valores —«Completado», «Cancelado», «En espera» e «Importado»— y un campo independiente «fulfillment_status» con cinco valores: «Sin tramitar», «Tramitado parcialmente», «Programado», «Rechazado» y «Tramitado». Un único evento «order.updated» puede notificar un cambio en cualquiera de estos campos.
Configure su endpoint de webhook.
La guía de integración explica paso a paso cómo registrar su endpoint y gestionar el ciclo de vida del pedido de principio a fin. La referencia completa de API incluye el esquema completo de lel payload.