Vývojáři · Referenční příručka k webhookům

Každá událost. Každý užitečný náklad. Podepsáno.

Fabrixa odesílá události týkající se objednávek na váš koncový bod v reálném čase. Váš server poskytuje jeden veřejný koncový bod typu POST; my odesíláme kompletní tělo objednávky s podpisem HMAC-SHA256 a tématem události v hlavičkách. Ověřte podpis, rychle vraťte stavový kód 200 a zpracujte objednávku asynchronně.

Přečtěte si průvodce integrací → Úplný referenční dokument k API

HMAC-SHA256 · order.created / order.updated · 10 opakovaných pokusů o doručení

Hlavičky požadavků

Žádost identifikují a ověřují tři hlavičky.

Každý webhook typu POST obsahuje vždy stejné tři hlavičky. Použijte x-webhook-topic pro směrování události a x-webhook-signature abyste si to ověřili, než dané instituci uvěříte.

content-type je vždy application/json. x-webhook-signature je hodnota HMAC-SHA256 v kódování Base64, získaná z nezpracovaného těla zprávy. x-webhook-topic je název události.

Příchozí hlavičky

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

Události webhooků

Dnes se budeme věnovat dvěma tématům.

Každý webhook je spuštěn konkrétním x-webhook-topic hodnota. Oba obsahují kompletní objekt objednávky, takže na daném tématu může pracovat jediný handler.

order.created

Byla zadána nová objednávka.

Spustí se při vytvoření objednávky v systému Fabrixa – ať už prostřednictvím požadavku API, nebo přímo v platformě.

order.updated

Stávající objednávka se mění.

Spustí se při změně podrobností objednávky – například při změně stavu objednávky nebo stavu vyřízení.

Stavy

Co mohou pole stavu vypovídat.

Údaje o nákladu obsahují objednávku status a také samostatný fulfillment_status. Zapněte tyto funkce a určujte si stav své objednávky sami.

Stav objednávek

Completed — odesláno nebo vyzvednuto a potvrzeno převzetí.
Canceled — platba byla zrušena; transakce nebyla dokončena.
On hold — objednávka je dočasně zablokována.
Imported — objednávka byla importována do platformy.

Stavy vyřízení objednávek

Unfulfilled — zatím nebylo připraveno ani odesláno.
Partially fulfilled — některé položky již byly zpracovány nebo odeslány, u jiných se čeká na vyřízení.
Scheduled — naplánováno a zařazeno do zpracování.
Rejected — žádost o splnění byla zamítnuta.
Fulfilled — plně zpracováno a dodáno nebo poskytnuto.

Payload

Jak tělo vypadá.

Celý text order.updated užitečná data, přesně tak, jak je popsáno v referenční dokumentaci API – objednávka, její stavy a řádky s podrobnostmi o variantách, produktech a zdrojích.

Tělo požadavku 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" }
        }
      ]
    }
  ]
}

Ověřte podpis

Znovu vypočítejte HMAC, porovnejte a poté důvěřujte obsahu.

Přepočítejte hodnotu HMAC-SHA256 surového obsahu požadavku pomocí svého tajného klíče, zakódujte ji pomocí Base64 a porovnejte s x-webhook-signature. Vždy používejte porovnání s konstantním časem (hash_equals), aby se zabránilo časovým útokům.

Č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čení a odpověď

Opakované pokusy a očekávaná odpověď.

Opakované pokusy

Až 10 pokusů, poté se funkce deaktivuje

Jakýkoli 2xx odpověď (např. 200) se považuje za úspěšnou, stejně jako 301 nebo 302 přesměrování. Jakékoli 4xx, 5xx nebo vypršení časového limitu spustí opakovaný pokus – celkem až 10krát. Po desátém neúspěšném pokusu se webhook deaktivuje.

Odpověď

Rychlý návrat s kódem 200, zpracování asynchronní

Potvrďte pomocí 200 OK co nejrychleji a následně zpracovat užitečná data asynchronně prostřednictvím úlohy na pozadí nebo fronty. Pomalý koncový bod lze považovat za selhání, i když se nakonec podaří provést požadavek.

Často kladené otázky

Webhooky, zodpovězeno

Jak ověřím podpis webhooku Fabrixa?

Znovu vypočítejte HMAC-SHA256 ze surového těla požadavku pomocí svého tajného klíče, výsledek zakódujte do formátu base64 a porovnejte jej s hlavičkou `x-webhook-signature` pomocí porovnání s konstantním časem, jako je například funkce `hash_equals`. Fabrixa poskytuje praktické příklady v čistém PHP a Laravelu; jakákoli neshoda by měla být odmítnuta ještě před zpracováním užitečného obsahu.

Jaké události webhooků odesílá Fabrixa?

Fabrixa odesílá dvě události, identifikované hlavičkou x-webhook-topic: „order.created“, která se spustí při zadání objednávky přes API nebo přímo na platformě, a „order.updated“, která se spustí při změně stavu objednávky nebo stavu vyřízení. Obě události obsahují kompletní objekt objednávky, takže na dané téma stačí nastavit pouze jednu obslužnou funkci.

Kolikrát systém Fabrixa opakuje pokus o neúspěšný webhook?

Fabrixa opakuje doručení webhooku až 10krát, pokud odpověď není 2xx, 301 nebo 302. Jakýkoli kód 4xx, 5xx nebo vypršení časového limitu se považuje za selhání a spustí se nový pokus; po desátém neúspěšném pokusu je webhook deaktivován, proto by koncový bod měl rychle vrátit kód 200 a zpracovat užitečná data asynchronně.

Jaké hlavičky obsahuje požadavek webhooku typu Fabrixa?

Každý webhook typu POST obsahuje tři hlavičky: content-type, vždy application/json; x-webhook-topic, označující událost, například order.updated; a x-webhook-signature, což je podpis HMAC-SHA256 surového těla zprávy zakódovaný v base64. Téma použijte k nasměrování události a podpis k její ověření, než důvěřujete obsahu.

Jaké stavy objednávek se objevují v datové části webhooku Fabrixa?

Datová část obsahuje pole status se čtyřmi hodnotami – Completed, Canceled, On hold a Imported – a samostatné pole fulfillment_status s pěti hodnotami: Unfulfilled, Partially fulfilled, Scheduled, Rejected a Fulfilled. Jedna událost typu order.updated může oznamovat změnu v kterémkoli z těchto polí.

Vytvořte si vlastní handler

Nakonfigurujte svůj koncový bod webhooku.

Průvodce integrací vás provede registrací vašeho koncového bodu a zpracováním celého životního cyklu objednávky od začátku do konce. Úplná referenční příručka k API obsahuje kompletní schéma datové náplně.

Přečtěte si průvodce integrací Úplný referenční dokument k API