Kehittäjät · Webhook-opas

Jokainen event. Jokainen payload. Allekirjoitettu.

Fabrixa välittää tilausilmoitukset päätepisteeseesi reaaliajassa. Palvelimesi tarjoaa yhden julkisen POST-päätepisteen; 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.

Lue integrointiohje → Koko API-dokumentaatio

HMAC-SHA256 · order.created / order.updated · 10 uudelleenkäynnistystä toimituksessa

Pyynnön otsikot

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 tarkista se ennen kuin luotat kyseiseen tahoon.

content-type on aina application/json. x-webhook-signature on raakasisällön base64-koodattu HMAC-SHA256-salaus. x-webhook-topic on tapahtuman nimi.

Saapuvat otsikot

{
  "content-type":        "application/json",
  "x-webhook-topic":     "order.updated",
  "x-webhook-signature": "YmEwNjBhMGMy...MAxMw=="
}

Webhook-tapahtumat

Tänään on kaksi aihetta.

Jokainen webhook laukeaa tietyn x-webhook-topic arvo. Molemmat sisältävät tilausobjektin kokonaisuudessaan, joten yksi käsittelijä voi reagoida aiheeseen.

order.created

Uusi tilaus on tehty.

Laukeaa, kun tilaus luodaan Fabrixa-järjestelmässä — joko API-pyynnön kautta tai suoraan alustalla.

order.updated

Olemassa oleva tilaus muuttuu.

Laukeaa, kun tilauksen tiedot muuttuvat — esimerkiksi tilauksen tila tai toimitustila muuttuu.

Tilat

Mitä tilakentät voivat kertoa.

Hyötykuorma sisältää sekä tilauksen status ja a fulfillment_status. Ota nämä käyttöön, jotta voit hallita tilauksesi tilaa itse.

Tilauksen tilat

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.

Toimitustilanteet

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.

Payload

Miltä keho näyttää.

Koko order.updated hyötykuorma, täsmälleen kuten API-viiteasiakirjassa on kuvattu — tilaus, sen tilat sekä rivit, joissa on variantti-, tuote- ja lähdetiedot.

POST-viestin runko — order.updated

{
  "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" }
        }
      ]
    }
  ]
}

Tarkista allekirjoitus

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.

Raaka PHP

$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');
}

Laravel

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…
}

Toimitus ja vastaus

Uudelleenkokeilut ja odotettu vastaus.

Uudelleenkokeilut

Enintään 10 yritystä, minkä jälkeen toiminto poistetaan käytöstä

A 2xx (esim. 200) tai a 301 / 302 lasketaan menestykseksi. Mikä tahansa 4xx, 5xx tai aikakatkaisu laukaisee uudelleenkokeilun — yhteensä enintään 10 kertaa. Kymmenennen epäonnistumisen jälkeen webhook poistetaan käytöstä.

Vastaus

Palauta 200 nopeasti, käsittele asynkronisesti

Vahvista seuraavalla 200 OK mahdollisimman nopeasti ja käsittele sitten hyötykuorma asynkronisesti taustatehtävän tai jonon avulla. Hidasta päätepistettä voidaan pitää epäonnistumisena, vaikka se lopulta onnistuisikin.

Luo oma käsittelijäsi

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.

Lue integrointiohje Koko API-dokumentaatio