Vývojári · Referenčná príručka k webhookom

Každá udalosť. Každý dátový náklad. Podpísané.

Fabrixa odosiela udalosti týkajúce sa objednávok na váš koncový bod v reálnom čase. Váš server sprístupňuje jeden verejný koncový bod typu POST; my odosielame celé telo objednávky s podpisom HMAC-SHA256 a témou udalosti v hlavičkách. Overte podpis, rýchlo vráťte kód 200 a spracujte asynchrónne.

Prečítajte si príručku k integrácii → Úplná referenčná štruktúra API

HMAC-SHA256 · order.created / order.updated · 10 pokusov o doručenie

Hlavičky požiadaviek

Žiadosť identifikujú a overujú tri hlavičky.

Každý webhook typu POST obsahuje tie isté tri hlavičky. Použite x-webhook-topic na smerovanie udalosti a x-webhook-signature aby ste si to overili, skôr než tomu uveríte.

content-type je vždy application/json. x-webhook-signature je hodnota HMAC-SHA256 v kódovaní base64, získaná z nezpracovaného tela správy. x-webhook-topic je názov udalosti.

Prichádzajúce hlavičky

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

Udalosti webhookov

Dnes budeme rozoberať dve témy.

Každý webhook je spustený konkrétnym x-webhook-topic hodnota. Obe obsahujú kompletný objekt objednávky, takže na danej téme môže pracovať jediný obslužný program.

order.created

Bola zadaná nová objednávka.

Spustí sa pri vytvorení objednávky v Fabrixa – buď prostredníctvom požiadavky API, alebo priamo na platforme.

order.updated

Existujúca objednávka sa mení.

Spustí sa pri zmene podrobností objednávky — napríklad pri zmene stavu objednávky alebo stavu vybavovania.

Stavy

Čo môžu vyjadrovať polia so stavom.

Úžitkové zaťaženie prenáša príkaz status ako aj samostatný fulfillment_status. Zapnite tieto funkcie, aby ste mohli riadiť stav svojej objednávky.

Stavy objednávok

Completed — odoslané alebo vyzdvihnuté a potvrdené prevzatie.
Canceled — platba bola zrušená; transakcia nebola dokončená.
On hold — objednávka je dočasne zablokovaná.
Imported — objednávka bola importovaná do platformy.

Stavy vybavovania

Unfulfilled — zatiaľ nie je pripravené ani odoslané.
Partially fulfilled — niektoré položky sú už spracované alebo odoslané, ostatné sú v procese vybavovania.
Scheduled — naplánované a zaradené do spracovania.
Rejected — žiadosť o splnenie bola zamietnutá.
Fulfilled — úplne spracované a dodané alebo sprístupnené.

Payload

Ako vyzerá telo.

Úplné znenie order.updated užitočné dáta, presne tak, ako to uvádzajú referenčné dokumenty API – objednávka, jej stavy a riadky s podrobnosťami o variante, produkte a zdroji.

Telo požiadavky POST — 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" }
        }
      ]
    }
  ]
}

Overte podpis

Prepočítajte HMAC, porovnajte a potom dôverujte obsahu.

Prepočítajte hodnotu HMAC-SHA256 surového obsahu požiadavky pomocou vášho tajného kľúča, zakódujte ju pomocou base64 a porovnajte s x-webhook-signature. Vždy používajte porovnanie s konštantným časom (hash_equals), aby sa zabránilo časovým útokom.

Čisté 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…
}

Doručenie a odpoveď

Opakované pokusy a očakávaná odpoveď.

Opakované pokusy

Až 10 pokusov, potom sa funkcia deaktivuje

Akýkoľvek 2xx odpoveď (napr. 200) sa považuje za úspešnú, rovnako ako 301 alebo 302 presmerovanie. Akékoľvek 4xx, 5xx alebo uplynutie časového limitu spustí opakovaný pokus — celkovo až 10-krát. Po desiatom neúspešnom pokuse sa webhook deaktivuje.

Odpoveď

Rýchly návrat s kódom 200, spracovanie asynchrónne

Potvrďte pomocou 200 OK čo najrýchlejšie a následne spracovať užitočné dáta asynchrónne prostredníctvom úlohy bežiacej na pozadí alebo fronty. Pomalý koncový bod možno považovať za zlyhanie, aj keď sa nakoniec podarí úlohu úspešne dokončiť.

Často kladené otázky

Webhooky, odpovede

Ako overím podpis webhooku Fabrixa?

Prepočítajte HMAC-SHA256 surového tela požiadavky pomocou vášho tajného kľúča, výsledok zakódujte pomocou base64 a porovnajte ho s hlavičkou x-webhook-signature pomocou porovnania s konštantným časom, napríklad hash_equals. Fabrixa poskytuje praktické príklady v čistom PHP a Laraveli, pričom akákoľvek nezhoda by mala byť odmietnutá ešte pred spracovaním dátovej časti.

Aké udalosti webhookov odosiela Fabrixa?

Fabrixa odosiela dve udalosti, identifikované hlavičkou x-webhook-topic: „order.created“, ktorá sa spustí pri zadaní objednávky prostredníctvom API alebo priamo na platforme, a „order.updated“, ktorá sa spustí pri zmene stavu objednávky alebo stavu jej vybavenia. Obe udalosti obsahujú kompletný objekt objednávky, takže na danú tému stačí jedna obslužná funkcia.

Koľkokrát systém Fabrixa opakuje pokus o neúspešný webhook?

Fabrixa opakuje odosielanie webhooku až 10-krát, ak odpoveď nie je 2xx, 301 alebo 302. Akýkoľvek kód 4xx, 5xx alebo časový limit sa považuje za zlyhanie a spustí sa ďalší pokus; po desiatom neúspešnom pokuse sa webhook deaktivuje, preto by koncový bod mal rýchlo vrátiť kód 200 a spracovať dátovú časť asynchrónne.

Aké hlavičky obsahuje žiadosť webhooku typu Fabrixa?

Každý webhook typu POST obsahuje tri hlavičky: content-type, vždy s hodnotou application/json; x-webhook-topic, ktorý označuje udalosť, napríklad order.updated; a x-webhook-signature, čo je podpis HMAC-SHA256 surového tela správy zakódovaný v base64. Tému použite na smerovanie udalosti a podpis na jej overenie, než dôverujete obsahu správy.

Aké stavy objednávok sa zobrazujú v obsahu webhooku Fabrixa?

Dátová časť obsahuje pole „status“ so štyrmi hodnotami – „Completed“, „Canceled“, „On hold“ a „Imported“ – a samostatné pole „fulfillment_status“ s piatimi hodnotami: „Unfulfilled“, „Partially fulfilled“, „Scheduled“, „Rejected“ a „Fulfilled“. Jedna udalosť typu „order.updated“ môže oznamovať zmenu v ktoromkoľvek z týchto polí.

Vytvorte si vlastný handler

Nakonfigurujte svoj koncový bod webhooku.

Príručka na integráciu vás prevedie registráciou vášho koncového bodu a spracovaním životného cyklu objednávky od začiatku až do konca. Úplná referenčná dokumentácia API obsahuje kompletnú schému dátovej náplne.

Prečítajte si príručku k integrácii Úplná referenčná štruktúra API