Elk event. Elke payload. Ondertekend.
Fabrixa stuurt bestelgebeurtenissen in realtime naar je endpoint. Je server stelt één openbaar POST-endpoint beschikbaar; wij sturen de volledige bestelgegevens met een HMAC-SHA256-handtekening en het event-topic in de headers. Controleer de handtekening, stuur snel een 200-statuscode terug en verwerk de gegevens asynchroon.
Drie headers identificeren en verifiëren het verzoek.
Elke POST-webhook bevat dezelfde drie headers. Gebruik x-webhook-topic om de gebeurtenis door te sturen en x-webhook-signature om dit te controleren voordat je de body vertrouwt.
content-type is altijd application/json. x-webhook-signature is de Base64-gecodeerde HMAC-SHA256 van de onbewerkte body. x-webhook-topic is de naam van het event.
{
"content-type": "application/json",
"x-webhook-topic": "order.updated",
"x-webhook-signature": "YmEwNjBhMGMy...MAxMw=="
}
Vandaag twee topics.
Elke webhook wordt geactiveerd door een specifieke x-webhook-topic waarde. Beide bevatten het volledige bestelobject, zodat één enkele handler op basis van het topic kan schakelen.
Er is een nieuwe bestelling geplaatst.
Wordt geactiveerd wanneer er een bestelling wordt aangemaakt in Fabrixa — hetzij via een API-verzoek, hetzij rechtstreeks in het platform.
Een bestaande bestelling wordt gewijzigd.
Wordt geactiveerd wanneer de bestelgegevens veranderen — bijvoorbeeld wanneer de bestelstatus of de fulfilmentstatus verandert.
Wat de statusvelden kunnen aangeven.
De lading bevat de bestelling status en daarnaast een aparte fulfillment_status. Schakel deze in om je eigen bestelstatus te bepalen.
- Completed — verzonden of afgehaald en ontvangst bevestigd.
- Canceled — de betaling is geannuleerd; de transactie is niet voltooid.
- On hold — de bestelling is tijdelijk geblokkeerd.
- Imported — de bestelling is in het platform geïmporteerd.
- Unfulfilled — nog niet opgesteld of verzonden.
- Partially fulfilled — sommige artikelen zijn al verwerkt of verzonden, andere staan nog in de wachtrij.
- Scheduled — gepland en ingepland voor verwerking.
- Rejected — het verzoek om uitvoering is afgewezen.
- Fulfilled — volledig verwerkt en geleverd of ter beschikking gesteld.
Hoe de body eruitziet.
De volledige order.updated payload, precies zoals de API-referentie die beschrijft — de bestelling, de statussen ervan en de rijen met gegevens over variant, product en bronbestand.
{
"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" }
}
]
}
]
}
Bereken de HMAC opnieuw, vergelijk de resultaten en vertrouw vervolgens de body.
Bereken de HMAC-SHA256 van de onbewerkte payload van het verzoek opnieuw met je geheime sleutel, codeer deze in Base64 en vergelijk deze met x-webhook-signature. Gebruik altijd een vergelijking met constante tijd (hash_equals) om timingaanvallen te voorkomen.
$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 en het antwoord dat we verwachten.
Maximaal 10 pogingen, daarna wordt de webhook uitgeschakeld
Elke 2xx een respons (bijv. 200) geldt als succes, net als een 301 of 302 omleiding. Elke 4xx, 5xx of time-out wordt er een nieuwe poging ondernomen — in totaal maximaal 10 keer. Na de tiende mislukte poging wordt de webhook gedeactiveerd.
Snel een 200-status retourneren, asynchroon verwerken
Bevestig met 200 OK zo snel mogelijk, en verwerk de payload vervolgens asynchroon via een achtergrondtaak of wachtrij. Een traag endpoint kan als een fout worden beschouwd, zelfs als het uiteindelijk toch lukt.
Webhooks, beantwoord
Hoe controleer ik de handtekening van een Fabrixa-webhook?
Bereken de HMAC-SHA256 van de onbewerkte verzoektekst opnieuw met behulp van je geheime sleutel, codeer het resultaat in Base64 en vergelijk het met de x-webhook-signature-header door middel van een vergelijking in constante tijd, zoals hash_equals. Fabrixa biedt uitgewerkte voorbeelden in pure PHP en Laravel, en elke afwijking moet worden afgewezen voordat de payload wordt verwerkt.
Welke webhook-gebeurtenissen verstuurt Fabrixa?
Fabrixa verstuurt twee gebeurtenissen, herkenbaar aan de x-webhook-topic-header: order.created, die wordt geactiveerd wanneer een bestelling wordt geplaatst via API of rechtstreeks in het platform, en order.updated, die wordt geactiveerd wanneer de bestelstatus of de fulfilmentstatus verandert. Beide bevatten het volledige bestelobject, zodat één handler op basis van het topic kan schakelen.
Hoe vaak probeert Fabrixa een mislukte webhook opnieuw?
Fabrixa probeert de verzending van een webhook maximaal 10 keer opnieuw wanneer het antwoord geen 2xx, 301 of 302 is. Elke 4xx-, 5xx-statuscode of time-out wordt als een mislukking beschouwd en leidt tot een retry; na de tiende mislukte poging wordt de webhook gedeactiveerd, dus het endpoint moet snel een 200-statuscode retourneren en de payload asynchroon verwerken.
Welke headers bevat een Fabrixa-webhookverzoek?
Elke POST-webhook bevat drie headers: content-type, altijd application/json; x-webhook-topic, waarin de gebeurtenis wordt benoemd, bijvoorbeeld order.updated; en x-webhook-signature, de in Base64 gecodeerde HMAC-SHA256-handtekening van de onbewerkte body. Gebruik het topic om de gebeurtenis te routeren en de handtekening om deze te verifiëren voordat je de payload vertrouwt.
Welke bestelstatussen worden weergegeven in de payload van een Fabrixa-webhook?
De payload bevat een statusveld met vier waarden — Completed, Canceled, On hold en Imported — en een apart veld fulfillment_status met vijf waarden: Unfulfilled, Partially fulfilled, Scheduled, Rejected en Fulfilled. Eén enkele order.updated-gebeurtenis kan een wijziging in een van beide velden melden.
Configureer je webhook-endpoint.
De integratiehandleiding leidt je stap voor stap door het registreren van je endpoint en het afhandelen van de volledige levenscyclus van een bestelling. De volledige API-referentie bevat het complete payload-schema.