Minden esemény. Minden hasznos adat. Aláírva.
Az Fabrixa valós időben továbbítja a megrendelési eseményeket a végpontodra. A szervered egy nyilvános POST végpontot tesz elérhetővé; mi a teljes megrendelés tartalmát küldjük el HMAC-SHA256 aláírással és a fejlécekben szereplő eseménytémával. Ellenőrizd az aláírást, azonnal küldj vissza 200-as kódot, majd aszinkron módon dolgozd fel az adatokat.
A kérés azonosítását és érvényesítését három fejléc biztosítja.
Minden webhook POST-kérés ugyanazt a három fejlécet tartalmazza. Használja a x-webhook-topic az esemény továbbításához és x-webhook-signature ellenőrizd le, mielőtt megbízol a szervezetben.
content-type mindig application/json. x-webhook-signature a nyers test Base64-kódolású HMAC-SHA256-értéke. x-webhook-topic ez az esemény neve.
{
"content-type": "application/json",
"x-webhook-topic": "order.updated",
"x-webhook-signature": "YmEwNjBhMGMy...MAxMw=="
}
Ma két téma lesz.
Minden webhookot egy adott x-webhook-topic érték. Mindkettő a teljes megrendelési objektumot hordozza, így egyetlen kezelő is át tud váltani a témára.
Új megrendelés érkezett.
Akkor aktiválódik, amikor egy megrendelés létrejön az Fabrixa-ben – akár API-kérés útján, akár közvetlenül a platformon.
Egy meglévő megrendelés módosul.
Akkor aktiválódik, amikor a megrendelés adatai megváltoznak – például a megrendelés állapota vagy a teljesítési állapot továbbhalad.
Mit árulhatnak el az állapotmezők?.
A hasznos teher hordozza a megrendelést status valamint egy különálló fulfillment_status. Kapcsold be ezeket, hogy saját rendelési állapotodat irányíthasd.
- Completed — kiszállítva vagy átvéve, és az átvétel megerősítve.
- Canceled — a fizetést törölték; a tranzakció nem zárult le.
- On hold — a megrendelés ideiglenesen felfüggesztésre került.
- Imported — a megrendelést feltöltötték a platformra.
- Unfulfilled — még nem készült el, illetve nem került elküldésre.
- Partially fulfilled — egyes tételeket már feldolgoztunk vagy kiszállítottunk, mások feldolgozása vagy kiszállítása még folyamatban van.
- Scheduled — feldolgozásra tervezve és ütemezve.
- Rejected — a teljesítési kérelmet elutasították.
- Fulfilled — teljes körűen feldolgozva és kiszállítva, illetve rendelkezésre bocsátva.
Hogyan néz ki a test?.
A teljes order.updated a hasznos adat, pontosan úgy, ahogyan azt az API referencia dokumentálja — a megrendelés, annak állapotai, valamint a változatot, a terméket és a beszerzési forrást tartalmazó sorok.
{
"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" }
}
]
}
]
}
Számítsd ki újra a HMAC-ot, hasonlítsd össze, majd fogadd el a tartalmat.
Számítsa ki újra a nyers kérelem hasznos adatainak HMAC-SHA256-értékét a titkos kulcsával, kódolja azt Base64-kódolással, majd hasonlítsa össze a x-webhook-signature. Mindig állandó időbeli összehasonlítást használj (hash_equals), hogy elkerüljék az időalapú támadásokat.
$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…
}
Újrakísérletek és a várt válasz.
Legfeljebb 10 kísérlet, utána letiltásra kerül
Bármelyik 2xx a válasz (pl. 200) sikernek minősül, akárcsak egy 301 vagy 302 átirányítás. Bármelyik 4xx, 5xx vagy a várakozási idő lejárta újbóli kísérletet vált ki – összesen legfeljebb 10-et. A tizedik sikertelen kísérlet után a webhook deaktiválásra kerül.
Gyors 200-as visszatérés, aszinkron feldolgozás
Erősítse meg a következővel: 200 OK a lehető leggyorsabban, majd a hasznos adatokat aszinkron módon kezelje háttérfeladat vagy sor segítségével. Egy lassú végpontot hiba esetén is kezelni lehet, még akkor is, ha végül sikerrel jár.
Webhookok – válaszok
Hogyan ellenőrizhetem egy Fabrixa webhook aláírását?
Számítsd ki újra a nyers kérelemtest HMAC-SHA256-értékét a titkos kulcsod segítségével, kódold az eredményt base64-kódolással, majd hasonlítsd össze az x-webhook-signature fejléccel egy állandó időbeli összehasonlító függvény, például a hash_equals segítségével. Az Fabrixa gyakorlati példákat nyújt nyers PHP-ben és Laravelben, és bármilyen eltérést el kell utasítani, mielőtt a hasznos adat feldolgozásra kerülne.
Milyen webhook-eseményeket küld az Fabrixa?
Az Fabrixa két eseményt küld, amelyeket az x-webhook-topic fejléc azonosít: az „order.created” eseményt, amelyet akkor vált ki, amikor megrendelés érkezik az API-n keresztül vagy közvetlenül a platformon, és az „order.updated” eseményt, amelyet akkor vált ki, amikor a megrendelés állapota vagy a teljesítés állapota megváltozik. Mindkettő a teljes megrendelési objektumot tartalmazza, így egy kezelő is kezelheti a témát.
Hányszor próbálja meg újra a Fabrixa egy sikertelen webhookot?
A Fabrixa legfeljebb 10-szer megkísérli újra a webhook továbbítását, ha a válasz nem 2xx, 301 vagy 302 kód. Bármely 4xx, 5xx kód vagy időtúllépés hibának minősül, és újraküldést vált ki; a tizedik sikertelen kísérlet után a webhook deaktiválódik, ezért a végpontnak gyorsan 200-as kódot kell visszaadnia, és a hasznos adatot aszinkron módon kell feldolgoznia.
Milyen fejléceket tartalmaz egy Fabrixa webhook-kérés?
Minden webhook POST-kérés három fejléccel rendelkezik: a content-type, amelynek értéke mindig application/json; az x-webhook-topic, amely megnevezi az eseményt (például order.updated); valamint az x-webhook-signature, amely a nyers testrész base64-kódolású HMAC-SHA256 aláírása. Használja a topic fejléceket az esemény továbbításához, az aláírást pedig annak ellenőrzéséhez, mielőtt megbízik a hasznos adatban.
Milyen rendelési állapotok jelennek meg egy Fabrixa webhook adatközvetítésében?
A hasznos adatcsomag tartalmaz egy állapotmezőt, amelynek négy értéke lehet — „Befejezve”, „Törölve”, „Felfüggesztve” és „Importálva” —, valamint egy külön „fulfillment_status” mezőt, amelynek öt értéke lehet: „Nem teljesítve”, „Részben teljesítve”, „Beütemezve”, „Elutasítva” és „Teljesítve”. Egyetlen „order.updated” esemény is jelentheti bármelyik mezőben bekövetkezett változást.
Állítsd be a webhook végpontodat.
Az integrációs útmutató végigvezeti Önt a végpont regisztrációján és a megrendelés életciklusának teljes kezelésén. A teljes API-referencia tartalmazza a teljes hasznosadat-sémát.