Iga sündmus. Iga andmepakett. Allkirjastatud.
Fabrixa edastab tellimussündmused teie lõpppunktile reaalajas. Teie server avaldab ühe avaliku POST-lõpppunkti; me saadame täieliku tellimuse sisu koos HMAC-SHA256-allkirjaga ja sündmuse teemaga päises. Kontrollige allkirja, saatke kiiresti vastus 200 ja töötlege asünkroonselt.
Päringu identifitseerimiseks ja kinnitamiseks kasutatakse kolme päist.
Iga webhooki POST-päring sisaldab samu kolme päist. Kasuta x-webhook-topic sündmuse suunamiseks ja x-webhook-signature kontrollige seda enne, kui usaldate seda asutust.
content-type on alati application/json. x-webhook-signature on toores sisu Base64-kodeeringus HMAC-SHA256. x-webhook-topic on ürituse nimi.
{
"content-type": "application/json",
"x-webhook-topic": "order.updated",
"x-webhook-signature": "YmEwNjBhMGMy...MAxMw=="
}
Täna on kaks teemat.
Iga webhooki käivitab konkreetne x-webhook-topic väärtus. Mõlemad sisaldavad täielikku tellimusobjekti, mistõttu saab üks käsitleja teemal vahetada.
Esitati uus tellimus.
Käivitatakse siis, kui Fabrixa-s luuakse tellimus – kas API-päringu kaudu või otse platvormis.
Olemasolev tellimus muutub.
Käivitatakse, kui tellimuse andmed muutuvad — näiteks kui tellimuse staatus või täitmise staatus muutub.
Mida staatusväljad võivad väljendada.
Andmepakett kannab käsku status samuti eraldi fulfillment_status. Lülita need sisse, et juhtida oma tellimuse staatust.
- Completed — saadetud või ära toodud ning kättesaamine kinnitatud.
- Canceled — makse tühistati; tehingut ei viidud lõpule.
- On hold — tellimus on ajutiselt blokeeritud.
- Imported — tellimus imporditi platvormile.
- Unfulfilled — pole veel valmis ega saadetud.
- Partially fulfilled — osa kaupadest on juba töödeldud või lähetatud, teised on veel ootel.
- Scheduled — töötlemiseks kavandatud ja ajakavasse paigutatud.
- Rejected — täitmistaotlus lükati tagasi.
- Fulfilled — täielikult töödeldud ja tarnitud või kättesaadavaks tehtud.
Kuidas keha välja näeb.
Täielik order.updated kasulik koormus, täpselt nii, nagu see on dokumenteeritud API-viitedokumentides – tellimus, selle staatused ning read, mis sisaldavad varianti, toodet ja allika üksikasju.
{
"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" }
}
]
}
]
}
Arvuta HMAC uuesti välja, võrdle tulemusi ja usalda seejärel sõnumi sisu.
Arvuta taotluse töötlemata andmete HMAC-SHA256 uuesti välja oma salajase võtmega, kodeeri see base64-koodiga ja võrdle tulemust x-webhook-signature. Kasutage alati konstantse ajaga võrdlust (hash_equals), et vältida ajastusrünnakuid.
$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…
}
Korduskatseid ja oodatav vastus.
Kuni 10 katset, seejärel blokeeritakse
Mis tahes 2xx vastus (nt 200) loetakse edukaks, samuti nagu 301 või 302 suunamine. Mis tahes 4xx, 5xx või kui aegumise korral käivitatakse uuesti proovimine — kokku kuni 10 korda. Pärast kümnendat ebaõnnestumist deaktiveeritakse webhook.
Tagasta 200 kiiresti, töötle asünkroonselt
Kinnitage järgmisega: 200 OK nii kiiresti kui võimalik, seejärel töötle andmeid asünkroonselt taustatöö või järjekorra kaudu. Aeglast lõpppunkti võib käsitleda veana isegi siis, kui see lõpuks õnnestub.
Webhookid, vastatud
Kuidas kontrollida Fabrixa-veebihooki allkirja?
Arvuta taotluse töötlemata sisu HMAC-SHA256 uuesti välja, kasutades oma salajast võtit, kodeeri tulemus base64-koodiga ja võrdle seda x-webhook-signature-pealkirjaga konstantse ajaga võrdlusfunktsiooni abil, näiteks hash_equals. Fabrixa pakub praktilisi näiteid puhtas PHP-s ja Laravelis ning kõik mittevastavused tuleks tagasi lükata enne andmepaketi töötlemist.
Milliseid webhooki sündmusi saadab Fabrixa?
Fabrixa saadab kaks sündmust, mida tähistab päise „x-webhook-topic“: „order.created“, mis käivitatakse, kui tellimus esitatakse API kaudu või otse platvormis, ning „order.updated“, mis käivitatakse, kui tellimuse staatus või täitmise staatus muutub. Mõlemad sisaldavad täielikku tellimuse objekti, mistõttu saab üks käitleja teemat jälgida.
Kui mitu korda proovib Fabrixa ebaõnnestunud webhooki uuesti?
Fabrixa proovib webhooki edastamist uuesti kuni 10 korda, kui vastus ei ole 2xx, 301 või 302. Iga 4xx-, 5xx-kood või ajalõpu ületamine loetakse ebaõnnestumiseks ja käivitab uue katse; pärast kümnendat ebaõnnestunud katset deaktiveeritakse webhook, seega peaks lõpppunkt kiiresti tagastama koodi 200 ja töötlema andmeid asünkroonselt.
Milliseid päiseid sisaldab Fabrixa-webhooki päring?
Iga webhooki POST-päring sisaldab kolme päist: content-type, mille väärtus on alati application/json; x-webhook-topic, mis nimetab sündmust, näiteks order.updated; ning x-webhook-signature, mis on toores sisu base64-kodeeritud HMAC-SHA256-allkiri. Kasutage teemat sündmuse suunamiseks ja allkirja selle kontrollimiseks, enne kui usaldate andmepaketti.
Millised tellimuse staatused kuvatakse Fabrixa-i veebihooki andmepaketis?
Andmepakett sisaldab staatusvälja, millel on neli väärtust – „Lõpetatud”, „Tühistatud”, „Ootel” ja „Imporditud” – ning eraldi välja „fulfillment_status”, millel on viis väärtust: „Täitmata”, „Osaliselt täidetud”, „Kavandatud”, „Tagasi lükatud” ja „Täidetud”. Üksainus sündmus „order.updated” võib kajastada muutust kummaski väljas.
Ühendage oma webhooki lõpppunkt.
Integreerimisjuhend annab ülevaate teie lõpppunkti registreerimisest ja tellimuse elutsükli haldamisest algusest lõpuni. Täielikus API-viites on esitatud kogu andmepaketi skeem.