Programeri · Referenca za webhooke

Svaki događaj. Svaki teret. Potpisano.

Fabrixa šalje događaje narudžbi na vaš krajnji punkt u stvarnom vremenu. Vaš poslužitelj izlaže jednu javnu POST krajnju točku; šaljemo cjelovito tijelo narudžbe s HMAC-SHA256 potpisom i temom događaja u zaglavljima. Provjerite potpis, brzo vratite 200 i obradite asinhrono.

Pročitajte vodič za integraciju → Potpuna API referenca

HMAC-SHA256 · datum.izdavanja / datum.ažuriranja · 10 pokušaja dostave

Zahtjevne glave

Tri zaglavlja identificiraju i provjeravaju zahtjev.

Svaki webhook POST nosi ista tri zaglavlja. Koristite x-webhook-topic da usmjeri događaj i x-webhook-signature Provjerite to prije nego što vjerujete tijelu.

content-type uvijek application/json. x-webhook-signature je base64 HMAC-SHA256 sirovog tijela. x-webhook-topic je naziv događaja.

Ulazni zaglavlja

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

Webhook događaji

Dvije teme danas.

Svaki webhook se pokreće specifičnim x-webhook-topic vrijednost. Oba nose cijeli objekt naloga, pa se jedan rukovatelj može prebacivati na temu.

narudžba.kreirana

Novi je nalog poslan.

Pokreće se kada se narudžba stvori u Fabrixa — bilo putem API zahtjeva ili izravno na platformi.

order.updated

Postojeći nalog se mijenja.

Pokreće se kada se promijene detalji narudžbe — na primjer status narudžbe ili status ispunjenja koji se mijenja.

Statusy

Što polja statusa mogu reći.

Pogonska jedinica nosi naredbu status kao i zaseban fulfillment_status. Uključite ih kako biste pokrenuli vlastitu državu narudžbe.

Stanja narudžbe

Completed — poslano ili preuzeto i potvrđen je račun.
Canceled — Plaćanje je otkazano; transakcija nije dovršena.
On hold — Nalog je privremeno blokiran.
Imported — Nalog je uvezen na platformu.

Status ispunjavanja

Unfulfilled — još nije pripremljeno ili poslano.
Partially fulfilled — neki artikli obrađeni ili poslani, drugi su u obradi.
Scheduled — planirano i zakazano za obradu.
Rejected — Zahtjev za ispunjenje je odbijen.
Fulfilled — u potpunosti obrađeno i isporučeno ili učinjeno dostupnim.

Payload

Kako tijelo izgleda.

Cijeli order.updated teret, točno onako kako ga referentni dokumenti API dokumentiraju — narudžba, njezini statusi i retci s detaljima o varijanti, proizvodu i izvoru.

POST tijelo — 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" }
        }
      ]
    }
  ]
}

Provjeri potpis

Ponovno izračunajte HMAC, usporedite, a zatim vjerujte tijelu.

Ponovno izračunajte HMAC-SHA256 sirovog tereta zahtjeva sa svojim tajnim ključem, dekodirajte ga u base64 i usporedite s x-webhook-signature. Uvijek koristite usporedbu konstantnog vremena (hash_equals) kako bi se izbjegli napadi na vremensko ograničenje.

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

Dostava i odgovor

Ponovni pokušaji i odgovor koji očekujemo.

Ponovni pokušaji

Do 10 pokušaja, zatim onemogućeno

Bilo koji 2xx odgovor (npr. 200) računa se kao uspjeh, kao i a 301 ili 302 preusmjeriti. Bilo koji 4xx, 5xx ili prekoračenje vremena pokreće ponovni pokušaj — do ukupno 10. Nakon desetog neuspjeha webhook se deaktivira.

Odgovor

Brzo vratite 200, obradite asinhrono

Potvrdite s 200 OK što je brže moguće, a zatim asinhrono obradite teret putem pozadinskog zadatka ili reda čekanja. Spori krajnji punkt može se smatrati neuspjehom čak i ako na kraju uspije.

Često postavljana pitanja

Webhooks, odgovoreno

Kako provjerim potpis Fabrixa webhooka?

Ponovno izračunajte HMAC-SHA256 sirovog tijela zahtjeva koristeći svoj tajni ključ, rezultat base64-enkodirajte i usporedite ga s zaglavljem x-webhook-signature pomoću usporedbe u konstantnom vremenu, kao što je hash_equals. Fabrixa pruža obrađene primjere u čistom PHP-u i Laravelu, a svaka neusklađenost treba biti odbijena prije obrade korisnog tereta.

Koje webhook događaje Fabrixa šalje?

Fabrixa šalje dva događaja, identificirana zaglavljem x-webhook-topic: order.created, koji se aktivira kada je narudžba postavljena putem API ili izravno na platformi, i order.updated, koji se aktivira kada se promijeni status narudžbe ili status ispunjenja. Oba prenose cijeli objekt narudžbe, pa se jedan handler može aktivirati na obje teme.

Koliko puta Fabrixa ponovno pokušava neuspjeli webhook?

Fabrixa do 10 puta ponovno pokušava isporuku webhooka kada odgovor nije 2xx, 301 ili 302. Svaki 4xx, 5xx ili prekoračenje vremena (timeout) računa se kao neuspjeh i pokreće ponovni pokušaj; nakon desetog neuspješnog pokušaja webhook se deaktivira, stoga krajnja točka treba brzo vratiti 200 i asinhrono obraditi payload.

Koje zaglavlje sadrži Fabrixa webhook zahtjev?

Svaki webhook POST nosi tri zaglavlja: content-type, uvijek application/json; x-webhook-topic, koje naziva događaj poput order.updated; i x-webhook-signature, HMAC-SHA256 potpis sirovog tijela kodiran u base64. Koristite temu za usmjeravanje događaja i potpis za njegovu provjeru prije povjerenja u teret.

Koji se status narudžbe pojavljuju u payloadu Fabrixa webhooka?

Teret sadrži polje statusa s četiri vrijednosti — Završeno, Otkazano, Na čekanju i Uvezeno — i zasebno polje fulfillment_status s pet vrijednosti: Nerasporedeno, Djelomično ispunjen, Zakazano, Odbijeno i Ispunjeno. Jedan događaj order.updated može prijaviti promjenu u bilo kojem od ta dva polja.

Izgradi svog ručatelja

Povežite svoju webhook krajnju točku.

Vodič za integraciju vodi vas kroz registraciju vašeg krajnjeg točka i upravljanje životnim ciklusom narudžbe od početka do kraja. Cjelovita API referenca sadrži potpunu shemu korisnog tereta.

Pročitajte vodič za integraciju Potpuna API referenca