SOFORT
Erstzustellung + Wiederholungsversuch 1
Erste Zustellung bei Ereignis. Wenn 5xx oder Timeout, 30 Sekunden später erneut versuchen.
ENTWICKLER - REFERENZ FÜR WEBHOOKS
Lebenszyklus-Ereignisse bestellen, signiert und wiederholungssicher.
Webhooks werden bei jedem Zustandswechsel der Bestellung ausgelöst: eingegangen, gedruckt, versandt, fehlgeschlagen. JSON über HTTPS, HMAC-SHA256 signiert zur Verifizierung, Wiederholungswarteschlange mit exponentiellem Backoff bis zu 24 Stunden. Ereignisreferenz, Beispiele für Signaturprüfcodes und Wiederholungsversuche / Dead-Letter-Politik unten.
HMAC-SHA256 SIGNED - AT-LEAST-ONCE - 24h RETRY - DEAD-LETTER QUEUE
VERANSTALTUNGSTYPEN
Fünf Ereignisse im Lebenszyklus eines Auftrags.
Abonnieren Sie eine beliebige Teilmenge auf der PUT /v1/account/webhook
Endpunkt. Die meisten Integrationen beziehen sich auf alle fünf.
| Veranstaltung | Brennt, wenn | Typische Aktion |
|---|---|---|
| Bestellung.erhalten | Fabrixa nahm den Auftrag an und vergab eine auftrag_id. Ack innerhalb von Sekunden nach POST. | Aktualisierung des internen Auftragsstatus auf "in Produktion"; Weiterleitung an den Endkunden. |
| Bestellung.gedruckt | Schritt Reaktivdruck abgeschlossen. Das Kleidungsstück wird zugeschnitten und genäht. Meilenstein in der Mitte der Produktion. | Optional - einige Teams verwenden diese Option für Endkunden-E-Mails mit dem Hinweis, dass Ihre Bestellung gerade bearbeitet wird. |
| Auftrag.versandt | Qualitätskontrolle, Verpackung, Übergabe an den Spediteur. Tracking-Nummer vergeben. | Aktualisieren des Bestellstatus auf "versandt"; Auslösen einer Versandbenachrichtigung für den Endkunden mit Tracking-URL. |
| Bestellung.geliefert | Der Spediteur hat die Zustellung an die Empfängeradresse bestätigt. | Auslösen von Abläufen nach dem Kauf: Anfrage nach einer Bewertung, Upsell von verwandten Produkten usw. |
| auftrag.fehlgeschlagen | Die Bestellung kann nicht abgeschlossen werden - die Vorlage ist nicht erreichbar, die Empfängeradresse ist ungültig, der Stoff ist für einen längeren Zeitraum nicht auf Lager. | Ticket öffnen / Ops benachrichtigen. Die Nutzlast umfasst fehler.code für die Einschaltlogik. |
PAYLOAD SHAPE
Gleicher Umschlag, ereignisspezifische Daten.
Gemeinsamer Umschlag (Ereignis, order_id, order_ref, Zeitstempel) plus eine ereignisspezifische
Daten Objekt. Verbrauchen Sie zuerst den Umschlag; schalten Sie Veranstaltung für die Datenform.
Auftrag.versandt
# order.dispatched payload - POST an Ihre Webhook-URL POST /ihr-webhook-endpunkt Inhalt-Typ: anwendung/json X-Fabrixa-Veranstaltung: order.dispatched X-Fabrixa-Unterschrift: t=1715173928,v1=ab3c4... X-Fabrixa-Lieferschein-Id: del_94kQ7r2L { "Ereignis": "auftrag.abgefertigt", "order_id": "ord_8e6f4b2a", "auftrag_ref": "shopify-1042", "Zeitstempel": "2026-05-15T11:32:08Z", "produktions_hub": "PT", "Daten": { "Verfolgung": { "Träger": "DHL", "tracking_number": "JJD0123456789", "tracking_url": "https://dhl.com/track/JJD0123456789", "geschätzte_Lieferung": "2026-05-19" }, "Empfänger": { "Name": "Lena Costa", "Stadt": "Porto", "Land": "PT" } } }
UNTERSCHRIFTENPRÜFUNG
HMAC-SHA256 über (Zeitstempel + Rohkörper).
Prüfen Sie die Unterschrift vor der Verarbeitung. Verwenden Sie die Rohdaten der Anfrage - nicht ein neu serialisiertes JSON-Objekt - sonst stimmt der HMAC nicht überein. Das Signiergeheimnis wird einmalig bei der Einrichtung der Webhook-URL ausgegeben; die Rotation erfolgt über das Dashboard.
unterschrift-überprüfen.js
// Node.js / Express Beispiel const Krypto = erfordern("Krypto"); app.Beitrag("/webhook", express.roh({ Typ: "application/json" }), (req, res) => { const signature = req.headers["x-fabrixa-Signatur"]; const [tPart, v1Part] = Unterschrift.geteilt(","); const Zeitstempel = tPart.geteilt("=")[1]; const empfangen = v1Part.geteilt("=")[1]; // Ablehnung von Ereignissen, die älter als 5 Minuten sind (Wiedergabeschutz) wenn (Math.abs(Datum.jetzt() / 1000 - Zeitstempel) > 300) return res.Status(400).Ende(); const payload = `${Zeitstempel}.${req.body.toString()}`; const erwartet = krypto .createHmac("sha256", process.env.FABRIXA_WEBHOOK_SECRET) .Update(Nutzlast) .Zusammenfassung("hex"); wenn (!crypto.timingSafeEqual(Puffer.von(empfangen), Puffer.von(erwartet))) { return res.Status(401).Ende(); } // Unterschrift gültig - Verarbeitung des Ereignisses const Ereignis = JSON.zerlegen.(req.body); handleEvent(event); res.Status(200).Ende(); });
Entsprechende Beispiele für Python (Flask), PHP, Ruby und Go befinden sich im Ordner scripts der Postman-Sammlung. timingSafeEqual ist wichtig - verwenden Sie keine String-Gleichheit, sie ist anfällig für Timing-Angriffe.
RÜCKGABE-POLITIK
Exponentieller Backoff bis zu 24 Stunden.
Die Webhook-Zustellung erfolgt mindestens einmalig. Wenn Ihr Endpunkt 5xx zurückgibt oder eine Zeitüberschreitung (10s Timeout), versuchen wir es nach einem exponentiellen Backoff-Zeitplan bis zu 24 Stunden lang erneut. Nach 24 Stunden landet das Ereignis in einer Warteschlange mit toten Buchstaben, die Sie manuell wiederholen können.
BACKOFF
Wiederholungen 2-8, exponentiell
60s → 5min → 30min → 2h → 6h → 12h → 24h. Bei jedem erneuten Versuch wird länger gewartet.
DEAD-LETTER
Nach 24 Stunden des Ausfalls
Ereignis wurde in die Warteschlange der toten Buchstaben verschoben. Wiederholen Sie es manuell über das Dashboard oder POST /v1/webhooks/replay/:delivery_id.
ORDER.FAILED EREIGNIS
Strukturierte Fehlerursachen für die Einschaltlogik.
Das operativ wichtigste Ereignis. Die Nutzlast umfasst eine stabile fehler.code string - sicher, um die automatische Weiterleitung, die Erstellung von Tickets oder die Benachrichtigung von Endkunden zu aktivieren.
auftrag.fehlgeschlagen
{
"Ereignis": "auftrag.fehlgeschlagen",
"order_id": "ord_8e6f4b2a",
"auftrag_ref": "shopify-1042",
"Zeitstempel": "2026-05-13T09:14:22Z",
"Daten": {
"Fehler": {
"code": "artwork_unreachable",
"Nachricht": "GET auf artwork_url fehlgeschlagen (Timeout 30s) nach 3 Versuchen",
"wiederholbar": wahr,
"Kontext": {
"artwork_url": "https://cdn.yourbrand.com/art/drop-001.png"
}
}
}
}
# Gemeinsame Fehlercodewerte:
# artwork_unreachable - Ihre Kunstwerk-URL hat nicht geantwortet
# artwork_invalid_format - die Datei konnte nicht geparst werden (versuchen Sie es mit PNG/Vektor-PDF)
# artwork_resolution_low - DPI zu niedrig für das gewählte Produkt
# address_invalid - Empfängeradresse wurde nicht validiert
# fabric_unavailable - Stoffbasis seit >7 Tagen nicht mehr auf Lager
# payment_method_failed - Abrechnung in der Datei abgelehnt
# compliance_flag - Auftrag, der durch die Überprüfung der Einhaltung der Vorschriften gekennzeichnet ist
TESTING
Auslösen von Musterereignissen ohne echte Aufträge.
POST /v1/webhooks/test
sendet ein synthetisches Ereignis eines beliebigen Typs an Ihre registrierte Webhook-URL.
Nützlich, um Ihren Handler zu testen, bevor Sie echte Aufträge erteilen, oder um
eines neuen Endpunkts nach einer Bereitstellung.
Sandbox-Webhooks liefern an Ihre Sandbox-URL. Verwenden Sie ein Tunneling-Tool (ngrok, Cloudflare Tunnel), um die Sandbox-Webhooks während der Entwicklung auf localhost Entwicklung.
POST /v1/webhooks/test
locken. -X POST $BASE_URL/v1/webhooks/test \ -H "Autorisierung: Bearer $KEY" \ -H "Inhalts-Typ: application/json" \ -d '{ "Ereignis": "auftrag.abgefertigt", "muster_auftrag_id": "Probe" }' # 200 OK { "lieferung_id": "del_test_94kQ", "posted_to": "https://your-tunnel.ngrok.io/webhook", "Status": "in der Warteschlange" }
IHREN WEBHOOK REGISTRIEREN
Geben Sie die URL einmal ein. Wir kümmern uns um die Zustellung.
Eine Webhook-URL pro Konto, alle Ereignistypen feuern auf diese URL. Filter auf die
Veranstaltung
Feld in Ihrem Handler. Die Einrichtung erfolgt über den Integrationsleitfaden.