Chaque event. Chaque payload. Signé.
Fabrixa transmet les événements liés aux commandes à votre endpoint en temps réel. Votre serveur expose un endpoint POST public ; nous envoyons le corps complet de la commande avec une signature HMAC-SHA256 et le sujet de l'événement dans les en-têtes. Vérifiez la signature, renvoyez rapidement un code de statut 200, puis traitez la commande de manière asynchrone.
Trois en-têtes permettent d'identifier et de vérifier la requête.
Chaque requête POST de webhook comporte les trois mêmes en-têtes. Utilisez x-webhook-topic pour acheminer l'événement et x-webhook-signature pour le vérifier avant de faire confiance au corps de la requête.
content-type est toujours application/json. x-webhook-signature correspond au HMAC-SHA256 encodé en Base64 du corps brut. x-webhook-topic est le nom de l'événement.
{
"content-type": "application/json",
"x-webhook-topic": "order.updated",
"x-webhook-signature": "YmEwNjBhMGMy...MAxMw=="
}
Deux sujets aujourd'hui.
Chaque webhook est déclenché par une valeur x-webhook-topic spécifique. Les deux contiennent l'objet de commande complet, ce qui permet à un seul gestionnaire d'aiguiller selon le topic.
Une nouvelle commande a été passée.
Se déclenche lorsqu'une commande est créée dans Fabrixa, que ce soit via une requête API ou directement sur la plateforme.
Une commande existante est modifiée.
Se déclenche lorsque les détails d'une commande changent — par exemple, lorsque le statut de la commande ou le statut de fulfilment évolue.
Ce que peuvent indiquer les champs d'état.
La charge utile contient la commande status ainsi qu’un autre fulfillment_status. Activez ces options pour gérer vous-même le statut de votre commande.
- Completed — expédié ou retiré, et réception confirmée.
- Canceled — Le paiement a été annulé ; la transaction n'a pas abouti.
- On hold — la commande est temporairement bloquée.
- Imported — la commande a été importée sur la plateforme.
- Unfulfilled — pas encore préparé ni envoyé.
- Partially fulfilled — certains articles ont été traités ou expédiés, d'autres sont en attente.
- Scheduled — traitement planifié et programmé.
- Rejected — la demande de fulfilment a été refusée.
- Fulfilled — entièrement traitées et livrées ou mises à disposition.
À quoi ressemble le corps ?
Le payload order.updated complet, exactement tel qu’il est décrit dans la documentation de référence API : la commande, ses statuts, ainsi que les lignes contenant les détails relatifs aux variantes, aux produits et aux sources.
{
"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" }
}
]
}
]
}
Recalculez le HMAC, comparez les résultats, puis considérez le corps du message comme fiable.
Recalculez la valeur HMAC-SHA256 du payload brut de la requête à l'aide de votre clé secrète, encodez-la en base64, puis comparez-la à x-webhook-signature. Utilisez toujours une comparaison en temps constant (hash_equals) afin d'éviter les attaques par temporisation.
$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…
}
Les retries et la réponse attendue.
Jusqu'à 10 tentatives, puis désactivé
N'importe quel 2xx une réponse (par exemple 200) est considérée comme un succès, tout comme un 301 ou 302 redirection. N'importe quelle 4xx, 5xx ou délai d'expiration déclenche un retry — jusqu'à 10 au total. Après le dixième échec, le webhook est désactivé.
Renvoyer rapidement un code d'état 200, traitement asynchrone
Répondre par 200 OK le plus rapidement possible, puis traiter le payload de manière asynchrone via une tâche en arrière-plan ou une file d'attente. Un endpoint lent peut être considéré comme un échec, même s'il finit par aboutir.
Webhooks : les réponses à vos questions
Comment vérifier la signature d'un webhook Fabrixa ?
Recalculez le HMAC-SHA256 du corps brut de la requête à l'aide de votre clé secrète, encodez le résultat en base64, puis comparez-le à l'en-tête x-webhook-signature à l'aide d'une fonction de comparaison en temps constant, telle que hash_equals. Fabrixa fournit des exemples concrets en PHP brut et en Laravel ; toute divergence doit être rejetée avant le traitement du payload.
Quels événements Webhook Fabrixa envoie-t-il ?
Fabrixa envoie deux événements, identifiés par l'en-tête x-webhook-topic : « order.created », déclenché lorsqu'une commande est passée via l'API ou directement sur la plateforme, et « order.updated », déclenché lorsque le statut de la commande ou son statut de fulfilment change. Ces deux événements contiennent l'objet de commande complet, ce qui permet à un seul gestionnaire d'aiguiller selon le sujet.
Combien de fois Fabrixa tente-t-il à nouveau d'envoyer un webhook qui a échoué ?
Fabrixa effectue jusqu'à 10 tentatives de transmission d'un webhook lorsque la réponse n'est pas un code 2xx, 301 ou 302. Tout code 4xx, 5xx ou délai d'expiration est considéré comme un échec et déclenche une nouvelle tentative ; après la dixième tentative infructueuse, le webhook est désactivé. L'endpoint doit donc renvoyer rapidement un code 200 et traiter le payload de manière asynchrone.
Quels en-têtes une requête de webhook Fabrixa contient-elle ?
Chaque requête POST de webhook comporte trois en-têtes : « content-type », toujours « application/json » ; « x-webhook-topic », qui désigne l'événement (par exemple « order.updated ») ; et « x-webhook-signature », la signature HMAC-SHA256 du corps brut, encodée en base64. Utilisez le sujet pour acheminer l'événement et la signature pour le vérifier avant de faire confiance au payload.
Quels statuts de commande apparaissent dans le payload d'un webhook Fabrixa ?
Le payload comporte un champ « status » proposant quatre valeurs — « Completed », « Canceled », « On hold » et « Imported » — ainsi qu'un champ distinct « fulfillment_status » proposant cinq valeurs : « Unfulfilled », « Partially fulfilled », « Scheduled », « Rejected » et « Fulfilled ». Un seul événement « order.updated » peut signaler une modification dans l'un ou l'autre de ces champs.
Configurez votre endpoint de webhook.
Le guide d'intégration vous explique étape par étape comment enregistrer votre endpoint et gérer le cycle de vie d'une commande de bout en bout. La documentation complète de l'API contient le schéma complet du payload.