IMMEDIATE
Livraison initiale + tentative 1
Première livraison sur l'événement. Si 5xx ou timeout, réessayer 30 secondes plus tard.
DÉVELOPPEURS - RÉFÉRENCE DES WEBHOOKS
Commande d'événements du cycle de vie, signée et sécurisée.
Les Webhooks se déclenchent à chaque transition d'état de la commande : reçue, imprimée, expédiée, échouée. JSON sur HTTPS, signé HMAC-SHA256 pour la vérification, file d'attente pour les tentatives avec exponentielle jusqu'à 24 heures. Référence de l'événement, exemples de code de vérification de la signature et de vérification de signature, et la politique de relance / lettre morte ci-dessous.
HMAC-SHA256 SIGNED - AT-LEAST-ONCE - 24h RETRY - DEAD-LETTER QUEUE
TYPES D'ÉVÉNEMENTS
Cinq événements du cycle de vie de la commande.
S'abonner à n'importe quel sous-ensemble sur le site PUT /v1/compte/webhook
point final. La plupart des intégrations souscrivent aux cinq.
| Événement | Se déclenche lorsque | Action typique |
|---|---|---|
| ordre.reçu | Fabrixa a accepté la commande et a assigné un order_id. Ack dans les secondes qui suivent le POST. | Mettre à jour le statut de la commande interne pour qu'elle soit "en cours de production" ; la surface est livrée au client final. |
| commande.imprimée | L'étape de l'impression réactive est terminée. Le vêtement passe à la coupe et à la couture. Étape de mi-production. | Facultatif - certaines équipes l'utilisent pour les courriels des clients finaux "votre commande est en cours de préparation". |
| order.dispatched | Contrôle de qualité, emballage, remise au transporteur. Numéro de suivi délivré. | Mise à jour du statut de la commande à "expédié" ; déclenchement d'une notification d'expédition au client final avec l'URL de suivi. |
| commande.livrée | Livraison confirmée par le transporteur à l'adresse du destinataire. | Déclencher des flux post-achat : demande d'évaluation, vente de produits connexes, etc. |
| commande.échouée | La commande ne peut être complétée - œuvre d'art inaccessible, adresse du destinataire invalide, tissu en rupture de stock pour une période prolongée. | Ouvrir un ticket / notifier les opérations. La charge utile comprend code.d'erreur pour la logique de mise en marche. |
FORME DE LA CHARGE
Même enveloppe, données spécifiques à l'événement.
Enveloppe commune (événement, order_id, order_ref, timestamp) plus une enveloppe spécifique à l'événement
données objet. Consommez d'abord l'enveloppe ; allumez événement pour la forme des données.
order.dispatched
# order.dispatched payload - POST à l'URL de votre webhook PUBLIER /votre-webhook-endpoint Content-Type: application/json X-Fabrixa-Event: order.dispatched X-Fabrixa-Signature: t=1715173928,v1=ab3c4... X-Fabrixa-Delivery-Id: del_94kQ7r2L { "événement": "order.dispatched", "order_id": "ord_8e6f4b2a", "order_ref": "shopify-1042", "horodatage": "2026-05-15T11:32:08Z", "production_hub": "PT", "données": { "suivi": { "transporteur": "DHL", "Numéro de suivi": "JJD0123456789", "tracking_url": "https://dhl.com/track/JJD0123456789", "livraison_estimée": "2026-05-19" }, "destinataire": { "nom": "Lena Costa", "ville": "Porto", "pays": "PT" } } }
VÉRIFICATION DE LA SIGNATURE
HMAC-SHA256 sur (horodatage + corps brut).
Vérifier la signature avant le traitement. Utiliser le corps de la demande brute - pas un objet JSON re-sérialisé - ou le HMAC ne correspondra pas. Le secret de signature est délivré une fois lorsque vous configurez l'URL du webhook ; la rotation se fait via le tableau de bord.
vérifier-signature.js
// Exemple Node.js / Express constante crypto = exiger("crypto") ; app.poste("/webhook", express.brut({ type : "application/json" }), (req, res) => { constante signature = req.headers["x-fabrixa-signature"]; constante [tPart, v1Part] = signature.diviser(","); constante horodatage = tPart.diviser("=")[1]; constante reçu = v1Part.diviser("=")[1]; // Rejeter les événements datant de plus de 5 minutes (protection contre le rejeu) si (Math.abs(Date.maintenant() / 1000 - horodatage) > 300) retour res.statut(400).fin(); constante payload = `${timestamp}.${req.body.toString()}`; constante attendu = crypto .créerHmac("sha256", process.env.FABRIXA_WEBHOOK_SECRET) .mise à jour(charge utile) .résumé("hexagone"); si (!crypto.timingSafeEqual(Tampon.de(reçu), Buffer.de(attendu))) { retour res.statut(401).fin(); } // Signature valide - traitement de l'événement constante événement = JSON.analyser(req.body) ; handleEvent(event) ; res.statut(200).fin(); });
Des exemples équivalents pour Python (Flask), PHP, Ruby et Go se trouvent dans le dossier scripts de la collection Postman. timingSafeEqual ne pas utiliser l'égalité des chaînes de caractères, car elle est vulnérable aux attaques temporelles.
POLITIQUE DE RETOUR
Retard exponentiel jusqu'à 24 heures.
La livraison des webhooks se fait au moins une fois. Si votre point d'accès renvoie 5xx ou s'il n'y a pas de délai d'attente (10s timeout), nous réessayons selon un calendrier exponentiel pour une durée maximale de 24 heures. Après 24 heures d'échec, l'événement est placé dans une file d'attente de lettres mortes que vous pouvez rejouer manuellement.
BACKOFF
Tentatives 2-8, exponentiel
60s → 5min → 30min → 2h → 6h → 12h → 24h. Chaque nouvelle tentative est plus longue.
DEAD-LETTER
Après 24 heures de défaillance
L'événement a été déplacé dans la file d'attente des lettres mortes. Relecture manuelle via le tableau de bord ou POST /v1/webhooks/replay/:delivery_id.
ÉVÉNEMENT ORDER.FAILED
Raisons d'erreur structurées pour la logique d'enclenchement.
L'événement le plus important sur le plan opérationnel. La charge utile comprend un code.d'erreur string - sécurité à activer pour le routage automatisé, la création de tickets ou la messagerie destinée aux clients finaux.
commande.échouée
{
"événement": "order.failed",
"order_id": "ord_8e6f4b2a",
"order_ref": "shopify-1042",
"horodatage": "2026-05-13T09:14:22Z",
"données": {
"erreur": {
"code": "artwork_unreachable" (œuvre d'art inaccessible)",
"message": "GET on artwork_url failed (timeout 30s) after 3 attempts" (GET sur artwork_url a échoué (timeout 30s) après 3 tentatives)",
"réessayable": vrai,
"contexte": {
"url_de_l'œuvre_d'art": "https://cdn.yourbrand.com/art/drop-001.png"
}
}
}
}
# Valeurs du code d'erreur commun :
# artwork_unreachable - l'URL de votre œuvre d'art n'a pas répondu
# artwork_invalid_format - n'a pas pu analyser le fichier (essayez PNG / vector PDF)
# artwork_resolution_low - DPI trop faible pour le produit choisi
# address_invalid - l'adresse du destinataire n'a pas été validée
# fabric_unavailable - base de tissu en rupture de stock depuis >7 jours
# payment_method_failed - billing on file declined (refus de facturation dans le dossier)
# compliance_flag - ordre marqué par un contrôle de conformité
TEST
Déclencher des événements types sans commandes réelles.
POST /v1/webhooks/test
envoie un événement synthétique de n'importe quel type à l'URL de votre webhook enregistré.
Utile pour tester votre gestionnaire avant de passer des commandes réelles, ou pour vérifier un nouveau point d'accès après un déploiement.
un nouveau point d'accès après un déploiement.
Les webhooks de la sandbox renvoient à l'URL de la sandbox. Utilisez un outil de tunnellisation (ngrok, Cloudflare Tunnel) pour faire pointer les webhooks de la sandbox sur localhost pendant le développement. développement.
POST /v1/webhooks/test
boucler -X POST $BASE_URL/v1/webhooks/test \N- -X POST $BASE_URL/v1/webhooks/test -H "Authorization : Bearer $KEY" \ -H "Content-Type : application/json" -d '{ "événement": "order.dispatched", "sample_order_id": "échantillon" }' # 200 OK { "delivery_id": "del_test_94kQ", "posted_to": "https://your-tunnel.ngrok.io/webhook", "statut": "en attente" }
ENREGISTRER VOTRE WEBHOOK
Définissez l'URL une seule fois. Nous nous chargeons de la livraison.
Une URL de webhook par compte, tous les types d'événements s'y connectent. Filtre sur l'URL
événement
dans votre gestionnaire. Configuration via le guide d'intégration.