Jokainen event. Jokainen payload. Allekirjoitettu.
Fabrixa välittää tilausilmoitukset endpointiisi reaaliajassa. Palvelimesi tarjoaa yhden julkisen POST-endpointin; lähetämme tilauksen koko sisällön, johon sisältyy HMAC-SHA256-allekirjoitus ja tapahtuman aihe otsikoissa. Tarkista allekirjoitus, palauta nopeasti vastauskoodi 200 ja käsittele tilaus asynkronisesti.
Kolme otsikkokenttää tunnistavat ja vahvistavat pyynnön.
Jokaisessa webhook-POST-pyynnössä on samat kolme otsikkoa. Käytä x-webhook-topic tapahtuman ohjaamiseksi ja x-webhook-signature sen varmentamiseksi ennen kuin luotat pyynnön sisältöön.
content-type on aina application/json. x-webhook-signature on raakasisällön base64-koodattu HMAC-SHA256-salaus. x-webhook-topic on tapahtuman nimi.
{
"content-type": "application/json",
"x-webhook-topic": "order.updated",
"x-webhook-signature": "YmEwNjBhMGMy...MAxMw=="
}
Tänään on kaksi aihetta.
Jokainen webhook laukeaa tietyn x-webhook-topic arvon perusteella. Molemmat sisältävät tilausobjektin kokonaisuudessaan, joten yksi käsittelijä voi reagoida aiheeseen.
Uusi tilaus on tehty.
Laukeaa, kun tilaus luodaan Fabrixa-järjestelmässä — joko API-pyynnön kautta tai suoraan alustalla.
Olemassa oleva tilaus muuttuu.
Laukeaa, kun tilauksen tiedot muuttuvat — esimerkiksi tilauksen tila tai toimitustila muuttuu.
Mitä tilakentät voivat kertoa.
Hyötykuorma kuljettaa tilauksen status sekä erillinen fulfillment_status. Ota nämä käyttöön, jotta voit hallita tilauksesi tilaa itse.
- Completed — lähetetty tai noudettu ja vastaanotto vahvistettu.
- Canceled — maksu peruutettiin; tapahtumaa ei saatu päätökseen.
- On hold — tilaus on väliaikaisesti jäädytetty.
- Imported — tilaus on tuotu alustalle.
- Unfulfilled — ei ole vielä valmisteltu tai lähetetty.
- Partially fulfilled — osa tuotteista on jo käsitelty tai lähetetty, osa on vielä käsittelyssä.
- Scheduled — suunniteltu ja aikataulutettu käsittelyä varten.
- Rejected — täyttämispyyntö hylättiin.
- Fulfilled — täysin käsitelty ja toimitettu tai saatettuna saataville.
Miltä keho näyttää.
Koko order.updated payload, täsmälleen kuten API-viiteasiakirjassa on kuvattu — tilaus, sen tilat sekä rivit, joissa on variantti-, tuote- ja lähdetiedot.
{
"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" }
}
]
}
]
}
Laske HMAC uudelleen, vertaa tuloksia ja luota sitten viestin sisältöön.
Laske pyynnön raakadatan HMAC-SHA256-arvo salaisella avaimellasi, koodaa se base64-muotoon ja vertaa tulosta x-webhook-signature. Käytä aina vakioaikavertausta (hash_equals) ajoitushyökkäysten estämiseksi.
$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…
}
Uudelleenkokeilut ja odotettu vastaus.
Enintään 10 yritystä, minkä jälkeen toiminto poistetaan käytöstä
Mikä tahansa 2xx vastaus (esim. 200) lasketaan onnistumiseksi, samoin kuin 301 tai 302 uudelleenohjaus. Mikä tahansa 4xx, 5xx tai aikakatkaisu laukaisee uudelleenkokeilun — yhteensä enintään 10 kertaa. Kymmenennen epäonnistumisen jälkeen webhook poistetaan käytöstä.
Palauta 200 nopeasti, käsittele asynkronisesti
Vahvista seuraavalla 200 OK mahdollisimman nopeasti ja käsittele sitten payload asynkronisesti taustatehtävän tai jonon avulla. Hidas endpoint voidaan katsoa epäonnistumiseksi, vaikka se lopulta onnistuisikin.
Webhookit, vastaukset
Miten voin tarkistaa Fabrixa-webhookin allekirjoituksen?
Laske raakamuotoisen pyynnön rungon HMAC-SHA256-arvo uudelleen salaisella avaimellasi, koodaa tulos base64-muotoon ja vertaa sitä x-webhook-signature-otsikkoon vakiovaiheisella vertailulla, kuten hash_equals-funktiolla. Fabrixa tarjoaa esimerkkejä raakakoodina PHP:llä ja Laravelilla, ja kaikki poikkeamat tulisi hylätä ennen kuin pyynnön sisältö käsitellään.
Mitä webhook-tapahtumia Fabrixa lähettää?
Fabrixa lähettää kaksi tapahtumaa, jotka tunnistetaan x-webhook-topic-otsikosta: order.created, joka laukeaa, kun tilaus tehdään API:n kautta tai suoraan alustalla, ja order.updated, joka laukeaa, kun tilauksen tila tai toimitustila muuttuu. Molemmat sisältävät täydellisen tilausobjektin, joten yksi käsittelijä voi vastata kyseiseen aiheeseen.
Kuinka monta kertaa Fabrixa yrittää epäonnistunutta webhookia uudelleen?
Fabrixa yrittää toimittaa webhookin uudelleen enintään 10 kertaa, jos vastaus ei ole 2xx, 301 tai 302. Mikä tahansa 4xx-, 5xx-koodi tai aikakatkaisu lasketaan epäonnistumiseksi ja laukaisee uudelleenkokeilun; kymmenennen epäonnistuneen yrityksen jälkeen webhook deaktivoidaan, joten päätepisteen tulisi palauttaa 200-vastaus nopeasti ja käsitellä hyötykuorma asynkronisesti.
Mitä otsikoita Fabrixa-webhook-pyyntö sisältää?
Jokaisessa webhook-POST-pyynnössä on kolme otsikkoa: content-type, joka on aina application/json; x-webhook-topic, joka nimeää tapahtuman, kuten order.updated; sekä x-webhook-signature, joka on raakasisällön base64-koodattu HMAC-SHA256-allekirjoitus. Käytä aihetta tapahtuman reitittämiseen ja allekirjoitusta sen todentamiseen ennen kuin luotat hyötykuormaan.
Mitkä tilausstatukset näkyvät Fabrixa-webhookin datapaketissa?
Payloadissa on tilakenttä, jossa on neljä arvoa — Valmis, Peruutettu, Pysäytetty ja Tuotu — sekä erillinen fulfillment_status-kenttä, jossa on viisi arvoa: Täyttämätön, Osittain täytetty, Aikataulutettu, Hylätty ja Täytetty. Yksittäinen order.updated-tapahtuma voi ilmoittaa muutoksesta kummassakin kentässä.
Määritä webhook-päätelaitteesi.
Integrointiohjeessa käydään läpi päätelaitteen rekisteröinti sekä tilauksen elinkaaren hallinta alusta loppuun. Koko API-dokumentaatio sisältää kattavan hyötykuormaskeeman.