Vsak dogodek. Vsak tovor. Podpisano.
Fabrixa v realnem času pošilja dogodke v zvezi z naročili na vašo končno točko. Vaš strežnik ponuja eno javno končno točko POST; mi pošljemo celotno besedilo naročila s podpisom HMAC-SHA256 in temo dogodka v glavah. Preverite podpis, hitro vrnite odziv 200 in obdelajte asinhrono.
Tri glave identificirajo in preverijo zahtevo.
Vsak POST-zahtevek webhooka vsebuje iste tri glave. Uporabite x-webhook-topic za usmerjanje dogodka in x-webhook-signature da to preverite, preden se zanesete na to institucijo.
content-type je vedno application/json. x-webhook-signature je HMAC-SHA256 v kodiranju Base64 neobdelanega telesa sporočila. x-webhook-topic je ime dogodka.
{
"content-type": "application/json",
"x-webhook-topic": "order.updated",
"x-webhook-signature": "YmEwNjBhMGMy...MAxMw=="
}
Danes bomo obravnavali dve temi.
Vsak webhook se sproži z določenim x-webhook-topic vrednost. Oba vsebujeta celoten objekt naročila, zato lahko en sam obdelovalec preklopi na temo.
Prejeto je novo naročilo.
Sproži se, ko je v sistemu Fabrixa ustvarjeno naročilo – bodisi prek zahtevka API bodisi neposredno v platformi.
Obstoječe naročilo se spremeni.
Sproži se, ko se spremenijo podrobnosti naročila — na primer status naročila ali status izpolnitve.
Kaj nam lahko povedo polja stanja.
Naklad prevaža naročilo status kot tudi ločen fulfillment_status. Vklopite te možnosti, da sami določite stanje svojega naročila.
- Completed — poslano ali prevzeto in prejem potrjen.
- Canceled — plačilo je bilo preklicano; transakcija ni bila zaključena.
- On hold — naročilo je začasno blokirano.
- Imported — naročilo je bilo uvoženo v platformo.
- Unfulfilled — še ni pripravljeno ali poslano.
- Partially fulfilled — nekateri izdelki so že obdelani ali odpremljeni, drugi pa še čakajo na obdelavo.
- Scheduled — načrtovano in razporejeno za obdelavo.
- Rejected — zahteva za izpolnitev je bila zavrnjena.
- Fulfilled — v celoti obdelano in dostavljeno ali dano na voljo.
Kako izgleda telo.
Celoten order.updated podatki o tovoru, točno tako, kot je to opisano v referenčnem dokumentu API – naročilo, njegovi statusi ter vrstice s podrobnostmi o variantah, izdelkih in virih.
{
"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" }
}
]
}
]
}
Ponovno izračunajte HMAC, primerjajte in nato zaupajte vsebini.
Ponovno izračunajte HMAC-SHA256 surovega podatkovnega dela zahtevka s svojim skrivnim ključem, ga kodirajte v base64 in primerjajte z x-webhook-signature. Vedno uporabljajte primerjavo s konstantnim časom (hash_equals), da bi se izognili časovnim napadom.
$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…
}
Ponovni poskusi in odgovor, ki ga pričakujemo.
Do 10 poskusov, nato se funkcija onemogoči
Kateri koli 2xx odgovor (npr. 200) se šteje za uspešen, prav tako pa tudi 301 ali 302 preusmeritev. Katera koli 4xx, 5xx ali pa se ob izteku časovne omejitve sproži ponovni poskus — skupaj največ 10-krat. Po desetem neuspešnem poskusu se webhook deaktivira.
Hitro vrni 200, obdelaj asinhrono
Potrdi z 200 OK čim prej, nato pa obdelajte vsebino asinhrono prek naloge v ozadju ali čakalne vrste. Počasno končno točko je mogoče obravnavati kot napako, tudi če se postopek na koncu uspešno zaključi.
Webhooki, odgovorjeno
Kako preverim podpis spletnega kljuka Fabrixa?
Ponovno izračunajte HMAC-SHA256 surovega telesa zahtevka z uporabo svojega skrivnega ključa, rezultat kodirajte v base64 in ga primerjajte z glavo x-webhook-signature s primerjavo v konstantnem času, na primer s funkcijo hash_equals. Fabrixa ponuja praktične primere v surovem PHP in Laravelu, vsako neskladje pa je treba zavrniti, preden se obdela vsebina zahtevka.
Katera dogodka webhooka pošilja Fabrixa?
Fabrixa pošilja dva dogodka, ki ju prepoznamo po glavi x-webhook-topic: »order.created«, ki se sproži ob oddaji naročila prek API ali neposredno na platformi, in »order.updated«, ki se sproži ob spremembi statusa naročila ali statusa izpolnitve. Oba dogodka vsebujeta celoten objekt naročila, zato lahko en obdelovalec spremlja to temo.
Kolikokrat Fabrixa ponovi neuspešen webhook?
Fabrixa ponovi pošiljanje webhooka do 10-krat, če odgovor ni 2xx, 301 ali 302. Vsak odziv 4xx, 5xx ali prekoračitev časovne omejitve se šteje za neuspeh in sproži ponovni poskus; po desetem neuspešnem poskusu se webhook deaktivira, zato mora končna točka hitro vrniti odziv 200 in asinhrono obdelati vsebino.
Katere glave vsebuje zahteva spletnega kljuka Fabrixa?
Vsak POST-zahtevek webhooka vsebuje tri glave: »content-type«, ki je vedno »application/json«; »x-webhook-topic«, ki poimenuje dogodek, na primer »order.updated«; ter »x-webhook-signature«, ki je v kodiranju base64 kodiran HMAC-SHA256 podpis surovega telesa zahtevka. Uporabite temo za usmerjanje dogodka in podpis za njegovo preverjanje, preden zaupate vsebini.
Kateri statusi naročil se pojavljajo v vsebini spletnega kljuka Fabrixa?
Podatkovni paket vsebuje polje status s štirimi vrednostmi – »Zaključeno«, »Preklicano«, »V čakanju« in »Uvoženo« – ter ločeno polje fulfillment_status s petimi vrednostmi: »Neizpolnjeno«, »Delno izpolnjeno«, »Načrtovano«, »Zavrnjeno« in »Izpolnjeno«. En sam dogodek »order.updated« lahko poroča o spremembi v katerem koli od teh polj.
Nastavite končno točko za webhook.
Vodnik za integracijo vas vodi skozi postopek registracije vaše končne točke in obravnavo celotnega življenjskega cikla naročila. Celotna referenca API vsebuje popolno shemo podatkovnega tovorja.