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 sowohl den status der Bestellung als auch einen 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
A 2xx (z. B. 200) oder ein 301 / 302 gilt als Erfolg. Jedes 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.
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.