Jedes Event. Jeder Payload. Signiert.
Fabrixa übermittelt Bestell-Events in Echtzeit an Ihren Endpoint. Ihr Server stellt einen öffentlichen POST-Endpoint bereit; wir senden den vollständigen Bestell-Body mit einer HMAC-SHA256-Signatur und dem Event-Topic in den Headern. Überprüfen Sie die Signatur, geben Sie umgehend den Status 200 zurück und verarbeiten Sie die Daten asynchron.
Drei Header dienen zur Identifizierung und Überprüfung der Anfrage.
Jeder Webhook-POST-Aufruf enthält dieselben drei Header. Verwenden Sie x-webhook-topic um das Event zu routen, und x-webhook-signature um es zu überprüfen, bevor Sie dem Body vertrauen.
content-type ist immer application/json. x-webhook-signature ist der Base64-HMAC-SHA256-Wert des Rohtextes. x-webhook-topic ist der Name des Events.
{
"content-type": "application/json",
"x-webhook-topic": "order.updated",
"x-webhook-signature": "YmEwNjBhMGMy...MAxMw=="
}
Heute gibt es zwei Topics.
Jeder Webhook wird durch einen bestimmten x-webhook-topic Wert ausgelöst. Beide enthalten das vollständige Bestell-Objekt, sodass ein einzelner Handler je nach Topic verzweigen kann.
Es wird eine neue Bestellung aufgegeben.
Wird ausgelöst, wenn eine Bestellung in Fabrixa angelegt wird – entweder über eine API-Anfrage oder direkt in der Plattform.
Eine bestehende Bestellung ändert sich.
Wird ausgelöst, wenn sich die Bestelldetails ändern – beispielsweise wenn sich der Bestellstatus oder der Fulfilment-Status ändert.
Was die Statusfelder aussagen können.
Der Payload enthält die Bestellung status sowie ein separates fulfillment_status. Verzweigen Sie auf diese Werte, um Ihren eigenen Bestellstatus zu steuern.
- Completed — versandt oder abgeholt und der Erhalt bestätigt.
- Canceled — Die Zahlung wurde storniert; die Transaktion wurde nicht abgeschlossen.
- On hold — Die Bestellung ist vorübergehend gesperrt.
- Imported — Die Bestellung wurde in die Plattform importiert.
- Unfulfilled — noch nicht vorbereitet oder versendet.
- Partially fulfilled — Einige Artikel wurden bereits bearbeitet oder versandt, andere stehen noch aus.
- Scheduled — zur Bearbeitung geplant und terminiert.
- Rejected — Die Fulfilment-Anfrage wurde abgelehnt.
- Fulfilled — vollständig bearbeitet und geliefert oder zur Verfügung gestellt.
Wie der Payload aussieht.
Der vollständige order.updated Payload, genau wie in der API-Referenz dokumentiert – die Bestellung, ihre Status sowie die Zeilen mit den Details zu Variante, Produkt und Quelldatei.
{
"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" }
}
]
}
]
}
Den HMAC neu berechnen, vergleichen und anschließend dem Payload vertrauen.
Berechnen Sie den HMAC-SHA256-Wert der Rohdaten der Anfrage mit Ihrem geheimen Schlüssel neu, kodieren Sie ihn in Base64 und vergleichen Sie ihn mit x-webhook-signature. Verwenden Sie stets einen Vergleich mit konstanter Laufzeit (hash_equals), um Timing-Angriffe zu vermeiden.
$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…
}
Retries und die erwartete Antwort.
Bis zu 10 Versuche, danach deaktiviert
Beliebige 2xx Eine Antwort (z. B. 200) gilt als Erfolg, ebenso wie eine 301 oder 302 Weiterleitung. Beliebig 4xx, 5xx oder ein Timeout löst einen erneuten Versuch aus – insgesamt bis zu 10 Mal. Nach dem zehnten Fehlversuch wird der Webhook deaktiviert.
Schnell 200 zurückgeben, asynchron verarbeiten
Bestätigen mit 200 OK so schnell wie möglich und bearbeiten Sie die Payloads anschließend asynchron über einen Hintergrundjob oder eine Warteschlange. Ein langsamer Endpoint kann als Fehler gewertet werden, auch wenn der Vorgang letztendlich erfolgreich ist.
Webhooks, beantwortet
Wie überprüfe ich die Signatur eines Fabrixa-Webhooks?
Berechnen Sie den HMAC-SHA256 des rohen Anfragetextes unter Verwendung Ihres geheimen Schlüssels neu, kodieren Sie das Ergebnis mit Base64 und vergleichen Sie es mit dem Header „x-webhook-signature“ mithilfe eines Vergleichs mit konstanter Laufzeit, wie z. B. „hash_equals“. Fabrixa stellt Anwendungsbeispiele in reinem PHP und Laravel zur Verfügung; jede Abweichung sollte abgelehnt werden, bevor die Nutzlast verarbeitet wird.
Welche Webhook-Events sendet Fabrixa?
Fabrixa sendet zwei Ereignisse, die durch den Header „x-webhook-topic“ gekennzeichnet sind: „order.created“, das ausgelöst wird, wenn eine Bestellung über API oder direkt in der Plattform aufgegeben wird, und „order.updated“, das ausgelöst wird, wenn sich der Bestellstatus oder der Bearbeitungsstatus ändert. Beide enthalten das vollständige Bestellobjekt, sodass ein Handler das Thema abhören kann.
Wie oft versucht Fabrixa, einen fehlgeschlagenen Webhook erneut auszuführen?
Fabrixa versucht die Zustellung eines Webhooks bis zu 10 Mal erneut, wenn die Antwort nicht 2xx, 301 oder 302 lautet. Jeder 4xx-, 5xx-Code oder ein Timeout gilt als Fehler und löst einen erneuten Versuch aus; nach dem zehnten fehlgeschlagenen Versuch wird der Webhook deaktiviert, daher sollte der Endpoint umgehend den Status 200 zurückgeben und die Payloads asynchron verarbeiten.
Welche Header enthält eine Fabrixa-Webhook-Anfrage?
Jeder Webhook-POST-Request enthält drei Header: „content-type“ (immer „application/json“); „x-webhook-topic“ (Bezeichnung des Ereignisses, z. B. „order.updated“); und „x-webhook-signature“ (die Base64-kodierte HMAC-SHA256-Signatur des Rohtextes). Verwenden Sie das „topic“, um das Ereignis weiterzuleiten, und die Signatur, um es zu überprüfen, bevor Sie der Nutzlast vertrauen.
Welche Bestellstatus werden in der Nutzlast eines Fabrixa-Webhooks angezeigt?
Der Payload enthält ein Statusfeld mit vier Werten – „Abgeschlossen“, „Storniert“, „Zurückgestellt“ und „Importiert“ – sowie ein separates Feld „fulfillment_status“ mit fünf Werten: „Nicht erfüllt“, „Teilweise erfüllt“, „Geplant“, „Abgelehnt“ und „Erfüllt“. Ein einzelnes „order.updated“-Ereignis kann eine Änderung in einem der beiden Felder melden.
Richten Sie Ihren Webhook-Endpoint ein.
Der Integrationsleitfaden führt Sie Schritt für Schritt durch die Registrierung Ihres Endpoints und die Abwicklung des gesamten Bestell-Lebenszyklus. Die vollständige API-Referenz enthält das vollständige Payload-Schema.