Udviklere · Vejledning til webhooks

Hvert event. Hver payload. Signeret.

Fabrixa sender ordrebegivenheder til dit endpoint i realtid. Din server stiller ét offentligt POST-endpoint til rådighed; vi sender den fulde ordretekst med en HMAC-SHA256-signatur og begivenhedsemnet i headerne. Bekræft signaturen, returner hurtigt en 200-statuskode, og behandl asynkront.

Læs integrationsvejledningen → Fuld API-reference

HMAC-SHA256 · order.created / order.updated · 10 forsøg på levering

Anmodningsheadere

Tre overskrifter identificerer og bekræfter anmodningen.

Hver POST-webhook indeholder de samme tre headere. Brug x-webhook-topic for at videresende begivenheden og x-webhook-signature at kontrollere det, før du stoler på organet.

content-type er altid application/json. x-webhook-signature er base64-kodningen af HMAC-SHA256 for den rå brødtekst. x-webhook-topic er navnet på begivenheden.

Indgående overskrifter

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

Webhook-begivenheder

Der er to emner i dag.

Hver webhook udløses af en bestemt x-webhook-topic værdi. Begge indeholder det fulde ordreobjekt, så en enkelt handler kan skifte mellem emnerne.

order.created

Der er afgivet en ny ordre.

Udløses, når der oprettes en ordre i Fabrixa — enten via en API-anmodning eller direkte i platformen.

order.updated

En eksisterende ordre ændres.

Udløses, når ordreoplysningerne ændres — for eksempel når ordrestatus eller leveringsstatus ændres fremadrettet.

Status

Hvad statusfelterne kan fortælle.

Nyttelasten rummer både en ordre status og en fulfillment_status. Aktiver disse for at styre din egen ordrestatus.

Ordrestatus

Completed — afsendt eller afhentet, og modtagelsen er bekræftet.
Canceled — betalingen blev annulleret; transaktionen blev ikke gennemført.
On hold — ordren er midlertidigt blokeret.
Imported — ordren blev importeret til platformen.

Ordrestatus

Unfulfilled — endnu ikke udarbejdet eller afsendt.
Partially fulfilled — nogle varer er blevet behandlet eller afsendt, andre er endnu ikke behandlet.
Scheduled — planlagt og sat på programmet til behandling.
Rejected — anmodningen om opfyldelse blev afvist.
Fulfilled — fuldt forarbejdet og leveret eller stillet til rådighed.

Payload

Hvordan kroppen ser ud.

Den fulde order.updated payload, præcis som beskrevet i API-referencedokumenterne — ordren, dens status og rækkerne med oplysninger om varianter, produkter og leverandører.

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

Bekræft underskriften

Beregn HMAC’en på ny, sammenlign, og betragt derefter brødteksten som pålidelig.

Genberegn HMAC-SHA256 for den rå anmodningsdata med din hemmelige nøgle, kod den med base64, og sammenlign med x-webhook-signature. Brug altid en sammenligning med konstant tid (hash_equals) for at undgå timing-angreb.

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

Levering og svar

Gentagelser og det svar, vi forventer.

Gentagelser

Op til 10 forsøg, derefter deaktiveret

A 2xx (f.eks. 200) eller en 301 / 302 regnes som en succes. Enhver 4xx, 5xx eller hvis der opstår en timeout, udløses et nyt forsøg — op til i alt 10 gange. Efter det tiende mislykkede forsøg deaktiveres webhooken.

Svar

Returner 200 hurtigt, behandl asynkront

Bekræft med 200 OK så hurtigt som muligt og derefter behandle nyttedataene asynkront via et baggrundsjob eller en kø. Et langsomt endpoint kan betragtes som en fejl, selvom det i sidste ende lykkes.

Opret din handler

Konfigurer dit webhook-endpoint.

Integrationsvejledningen gennemgår registreringen af dit endpoint og håndteringen af ordrens livscyklus fra start til slut. Den fulde API-reference indeholder det komplette skema for nyttedata.

Læs integrationsvejledningen Fuld API-reference