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.
Trzy nagłówki służą do identyfikacji i weryfikacji żądania.
Każde żądanie POST typu webhook zawiera te same trzy nagłówki. Użyj x-webhook-topic aby przekierować zdarzenie i x-webhook-signature aby je zweryfikować przed zaufaniem treści żądania.
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.
{
"content-type": "application/json",
"x-webhook-topic": "order.updated",
"x-webhook-signature": "YmEwNjBhMGMy...MAxMw=="
}
Dzisiaj poruszymy dwa tematy.
Każdy webhook jest uruchamiany przez konkretną x-webhook-topic wartość. Oba zawierają pełny obiekt zamówienia, więc jeden handler może przełączać się na podstawie tematu.
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.
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.
Co mogą oznaczać pola stanu.
Ładunek zawiera zamówienie status a także osobny fulfillment_status. Należy oprzeć na nich logikę, aby samodzielnie zarządzać stanem zamówienia.
- 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.
- 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.
Jak wygląda to ciało.
Pełna wersja order.updated payload, 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.
{
"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" }
}
]
}
]
}
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.
$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…
}
Ponowne próby i oczekiwana odpowiedź.
Maksymalnie 10 prób, po czym funkcja zostanie wyłączona
Każdy 2xx odpowiedź (np. 200) jest traktowana jako sukces, podobnie jak 301 lub 302 przekierowanie. Dowolne 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.
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.
Webhooki – odpowiedzi
Jak zweryfikować podpis webhooka Fabrixa?
Oblicz ponownie HMAC-SHA256 surowej treści żądania przy użyciu swojego klucza tajnego, zakoduj wynik w base64, a następnie porównaj go z nagłówkiem `x-webhook-signature` za pomocą funkcji porównującej w stałym czasie, takiej jak `hash_equals`. Fabrixa udostępnia gotowe przykłady w czystym PHP i Laravelu, a wszelkie niezgodności powinny zostać odrzucone przed przetworzeniem treści żądania.
Jakie zdarzenia webhookowe wysyła Fabrixa?
Fabrixa wysyła dwa zdarzenia, identyfikowane za pomocą nagłówka x-webhook-topic: „order.created”, wyzwalane w momencie złożenia zamówienia za pośrednictwem API lub bezpośrednio na platformie, oraz „order.updated”, wyzwalane w momencie zmiany statusu zamówienia lub statusu realizacji. Oba zawierają pełny obiekt zamówienia, więc jeden program obsługujący może monitorować ten temat.
Ile razy usługa Fabrixa ponawia próbę wysłania nieudanego webhooka?
Fabrixa ponawia próbę dostarczenia webhooka maksymalnie 10 razy, jeśli odpowiedź nie ma kodu 2xx, 301 lub 302. Każdy kod 4xx, 5xx lub przekroczenie limitu czasu jest traktowane jako niepowodzenie i powoduje ponowną próbę; po dziesiątej nieudanej próbie webhook zostaje dezaktywowany, dlatego punkt końcowy powinien szybko zwrócić kod 200 i przetworzyć ładunek asynchronicznie.
Jakie nagłówki zawiera żądanie webhooka typu Fabrixa?
Każdy żądanie POST typu webhook zawiera trzy nagłówki: content-type, zawsze o wartości application/json; x-webhook-topic, określający nazwę zdarzenia, np. order.updated; oraz x-webhook-signature, czyli zakodowany w base64 podpis HMAC-SHA256 surowej treści żądania. Należy wykorzystać temat do przekierowania zdarzenia, a podpis do jego weryfikacji przed zaufaniem do treści.
Jakie statusy zamówień pojawiają się w treści webhooka Fabrixa?
Dane użytkowe zawierają pole statusu z czterema wartościami — „Zrealizowane”, „Anulowane”, „Wstrzymane” i „Zaimportowane” — oraz osobne pole fulfillment_status z pięcioma wartościami: „Niezrealizowane”, „Częściowo zrealizowane”, „Zaplanowane”, „Odrzucone” i „Zrealizowane”. Pojedyncze zdarzenie „order.updated” może zgłaszać zmianę w dowolnym z tych pól.
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.