Programiści · Dokumentacja dotycząca webhooków

Każdy event. Każdy payload. Podpisany.

Fabrixa przesyła zdarzenia związane z zamówieniami do Państwa punktu końcowego w czasie rzeczywistym. Państwa serwer udostępnia jeden publiczny punkt końcowy POST; wysyłamy pełną treść zamówienia wraz z podpisem HMAC-SHA256 oraz tematem zdarzenia w nagłówkach. Zweryfikuj podpis, szybko zwróć kod 200 i przetwórz dane asynchronicznie.

Przeczytaj przewodnik po integracji → Pełna dokumentacja API

HMAC-SHA256 · order.created / order.updated · 10 prób ponownej dostawy

Nagłówki żądania

Trzy nagłówki służą do identyfikacji i weryfikacji żądania.

Każdy żądanie POST typu webhook zawiera te same trzy nagłówki. Użyj x-webhook-topic aby przekierować zdarzenie i x-webhook-signature aby to sprawdzić, zanim zaufasz tej instytucji.

content-type jest zawsze application/json. x-webhook-signature jest to kod Base64 algorytmu HMAC-SHA256 surowej treści. x-webhook-topic to nazwa wydarzenia.

Nadeszłe nagłówki

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

Zdarzenia webhooków

Dzisiaj poruszymy dwa tematy.

Każdy webhook jest uruchamiany przez konkretny x-webhook-topic wartość. Oba zawierają pełny obiekt zamówienia, więc jeden handler może przełączać się na dany temat.

order.created

Złożono nowe zamówienie.

Wyzwalane w momencie utworzenia zlecenia w systemie Fabrixa — zarówno na podstawie zlecenia z systemu API, jak i bezpośrednio na platformie.

order.updated

Istniejące zamówienie ulega zmianie.

Uruchamia się w przypadku zmiany szczegółów zamówienia — na przykład zmiany statusu zamówienia lub statusu realizacji.

Statusy

Co mogą oznaczać pola stanu.

Ładunek zawiera zarówno zamówienie status oraz a fulfillment_status. Włącz te opcje, aby samodzielnie zarządzać stanem zamówienia.

Statusy zamówień

Completed — wysłane lub odebrane, a odbiór potwierdzony.
Canceled — płatność została anulowana; transakcja nie doszła do skutku.
On hold — zamówienie zostało tymczasowo zablokowane.
Imported — zamówienie zostało zaimportowane do platformy.

Statusy realizacji zamówień

Unfulfilled — jeszcze nie przygotowane ani nie wysłane.
Partially fulfilled — niektóre pozycje zostały już przetworzone lub wysłane, inne są w toku.
Scheduled — zaplanowane i wpisane do harmonogramu przetwarzania.
Rejected — wniosek o realizację został odrzucony.
Fulfilled — w pełni przetworzone i dostarczone lub udostępnione.

Payload

Jak wygląda to ciało.

Pełna wersja order.updated dane użytkowe, dokładnie tak, jak opisano to w dokumentacji referencyjnej API — zamówienie, jego statusy oraz wiersze zawierające szczegóły dotyczące wariantu, produktu i źródła.

Treść żądania 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" }
        }
      ]
    }
  ]
}

Sprawdź podpis

Oblicz ponownie HMAC, porównaj wyniki, a następnie uznaj treść za wiarygodną.

Oblicz ponownie wartość HMAC-SHA256 surowej treści żądania przy użyciu swojego klucza tajnego, zakoduj ją w base64 i porównaj z x-webhook-signature. Należy zawsze stosować porównanie o stałym czasie (hash_equals), aby zapobiec atakom czasowym.

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

Dostawa i obsługa

Ponowne próby i oczekiwana odpowiedź.

Ponowne próby

Maksymalnie 10 prób, po czym funkcja zostanie wyłączona

A 2xx (np. 200) lub 301 / 302 liczy się jako sukces. Każdy 4xx, 5xx lub upływ limitu czasu powoduje ponowną próbę — łącznie do 10 razy. Po dziesiątej nieudanej próbie webhook zostaje wyłączony.

Odpowiedź

Szybki zwrot kodu 200, przetwarzanie asynchroniczne

Potwierdź za pomocą 200 OK jak najszybciej, a następnie przetworzyć dane w trybie asynchronicznym za pomocą zadania w tle lub kolejki. Powolny punkt końcowy można uznać za awarię, nawet jeśli ostatecznie zakończy się sukcesem.

Stwórz swój handler

Skonfiguruj punkt końcowy webhooka.

W przewodniku integracyjnym opisano krok po kroku proces rejestracji punktu końcowego oraz obsługę cyklu życia zamówienia od początku do końca. Pełna dokumentacja referencyjna API zawiera kompletny schemat danych.

Zapoznaj się z przewodnikiem po integracji Pełna dokumentacja API