Utvecklare · Referens för webhooks

Varje event. Varje payload. Signerad.

Fabrixa skickar orderhändelser till din slutpunkt i realtid. Din server tillhandahåller en offentlig POST-slutpunkt; vi skickar hela orderinnehållet med en HMAC-SHA256-signatur och händelseämnet i rubrikerna. Verifiera signaturen, returnera snabbt statuskoden 200 och bearbeta asynkront.

Läs integrationsguiden → Fullständig API-referens

HMAC-SHA256 · order.created / order.updated · 10 försök vid leverans

Begäran-rubriker

Tre rubriker identifierar och verifierar begäran.

Varje POST-webhook innehåller samma tre rubriker. Använd x-webhook-topic för att vidarebefordra händelsen och x-webhook-signature för att kontrollera det innan du litar på organisationen.

content-type är alltid application/json. x-webhook-signature är Base64-kodningen av HMAC-SHA256 för det obearbetade innehållet. x-webhook-topic är evenemangets namn.

Inkommande rubriker

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

Webhook-händelser

Två ämnen idag.

Varje webhook utlöses av en specifik x-webhook-topic värde. Båda innehåller hela orderobjektet, vilket innebär att en enda hanterare kan växla mellan ämnena.

order.created

En ny beställning har lagts.

Utlöses när en order skapas i Fabrixa – antingen via en API-förfrågan eller direkt i plattformen.

order.updated

En befintlig beställning ändras.

Utlöses när orderuppgifterna ändras – till exempel när orderstatusen eller leveransstatusen ändras framöver.

Status

Vad statusfälten kan visa.

Nyttolasten innehåller både en beställning status och en fulfillment_status. Aktivera dessa för att styra ditt eget orderstatus.

Orderstatus

Completed — levererad eller avhämtad och mottagandet bekräftat.
Canceled — betalningen avbröts; transaktionen genomfördes inte.
On hold — beställningen är tillfälligt spärrad.
Imported — beställningen har importerats till plattformen.

Leveransstatus

Unfulfilled — har ännu inte förberetts eller skickats.
Partially fulfilled — vissa artiklar har behandlats eller skickats, andra väntar på behandling.
Scheduled — planerade och schemalagda för bearbetning.
Rejected — begäran om uppfyllande avslogs.
Fulfilled — helt färdigbehandlade och levererade eller ställda till förfogande.

Payload

Hur kroppen ser ut.

Hela order.updated nyttolasten, precis som den beskrivs i API-referensdokumentet – beställningen, dess statusar och raderna med uppgifter om varianter, produkter och leverantörer.

POST-innehåll — 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" }
        }
      ]
    }
  ]
}

Kontrollera signaturen

Beräkna HMAC på nytt, jämför och lita sedan på meddelandetexten.

Beräkna HMAC-SHA256 på den obearbetade begäranens nyttolast med din hemliga nyckel, kod den med base64 och jämför med x-webhook-signature. Använd alltid en jämförelse med konstant tid (hash_equals) för att undvika tidsbaserade attacker.

Rå 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…
}

Leverans och svar

Omförsök och det svar vi förväntar oss.

Nya försök

Upp till 10 försök, därefter inaktiveras funktionen

A 2xx (t.ex. 200) eller en 301 / 302 räknas som en framgång. Varje 4xx, 5xx eller om tidsgränsen överskrids utlöses ett nytt försök – upp till totalt 10 stycken. Efter det tionde misslyckandet inaktiveras webhooken.

Svar

Returnera 200 snabbt, bearbeta asynkront

Bekräfta med 200 OK så snabbt som möjligt och hantera sedan nyttolasten asynkront via ett bakgrundsjobb eller en kö. En långsam slutpunkt kan betraktas som ett fel även om den till slut lyckas.

Skapa din hanterare

Konfigurera din webhook-ändpunkt.

Integrationsguiden beskriver hur du registrerar din slutpunkt och hanterar ordercykeln från början till slut. Den fullständiga API-referensen innehåller det fullständiga schemat för nyttolasten.

Läs integrationsguiden Fullständig API-referens