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 transporte à la fois une commande status et un 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é
A 2xx (par exemple 200) ou un 301 / 302 est considéré comme un succès. Tout 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.
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 de la charge utile.