Overslaan naar hoofdinhoud

Webhooks referentie

Fabrixa webhooks referentie - bestelstatus gebeurtenissen, ondertekende payloads, real-time integratie
ONTWIKKELAARS - WEBHOOKS REFERENTIE

Levenscyclusgebeurtenissen bestellen, ondertekend en beveiligd tegen opnieuw proberen.

Webhooks worden geactiveerd bij elke statusovergang van een bestelling: ontvangen, afgedrukt, verzonden, mislukt. JSON over HTTPS, HMAC-SHA256 ondertekend voor verificatie, wachtrij voor nieuwe pogingen met exponentiële backoff tot 24 uur. Eventreferentie, codevoorbeelden voor handtekeningverificatie en retry / dode letter beleid hieronder.

HMAC-SHA256 ondertekend - OPLAAT - 24u RETRY - DEAD-LETTER QUEUE

SOORTEN EVENEMENTEN

Vijf levenscyclusgebeurtenissen voor bestellingen.

Abonneer je op een subset op de PUT /v1/account/webhook eindpunt. De meeste integraties abonneren zich op alle vijf.

Evenement Vuurt wanneer Typische actie
order.ontvangenFabrixa accepteerde de bestelling en wees een order_id. Ack binnen enkele seconden na POST.Interne bestelstatus bijwerken naar "in productie"; oppervlakte naar eindklant.
bestelling.afgedruktReactieve printstap voltooid. Kledingstuk gaat naar knippen en naaien. Mijlpaal halverwege de productie.Optioneel - sommige teams gebruiken dit voor e-mails naar eindklanten "uw bestelling wordt gemaakt".
order.verzondenKwaliteitscontrole, verpakking, overhandiging aan vervoerder. Trackingnummer uitgegeven.Bestelstatus bijwerken tot "verzonden"; verzendbericht voor eindklant met URL voor tracering activeren.
bestelling.geleverdDe bezorging op het adres van de ontvanger is door de koerier bevestigd.Post-purchase flows triggeren: beoordelingsverzoek, upsell gerelateerd product, enz.
order.misluktBestelling kan niet worden voltooid - kunstwerk onbereikbaar, adres ontvanger ongeldig, stof langere tijd niet op voorraad.Open ticket / stel ops op de hoogte. Payload omvat error.code voor inschakellogica.
LADINGSVORM

Zelfde enveloppe, gebeurtenis-specifieke gegevens.

Gemeenschappelijke envelop (gebeurtenis, order_id, order_ref, tijdstempel) plus een gebeurtenis-specifieke gegevens object. Consumeer eerst de envelop; schakel evenement voor de gegevensvorm.

order.verzonden
# order.dispatched payload - POST naar uw webhook URL

POST /uw-webhook-eindpunt
Inhoudstype: toepassing/json
X-Fabrixa-gebeurtenis: order.verzonden
X-Fabrixa-handtekening: t=1715173928,v1=ab3c4...
X-Fabrixa-Levering-Iddel_94kQ7r2L

{
  "gebeurtenis":        "order.verzonden",
  "order_id":     "ord_8e6f4b2a",
  "order_ref":    "shopify-1042",
  "timestamp":    "2026-05-15T11:32:08Z",
  "productie_hub": "PT",
  "data": {
    "volgen": {
      "drager":         "DHL",
      "tracking_number": "JJD0123456789",
      "tracking_url":    "https://dhl.com/track/JJD0123456789",
      "geschatte_levering": "2026-05-19"
    },
    "ontvanger": {
      "naam":    "Lena Costa",
      "stad":    "Porto",
      "land": "PT"
    }
  }
}
HANDTEKENINGVERIFICATIE

HMAC-SHA256 over (tijdstempel + onbewerkte inhoud).

Controleer de handtekening voor verwerking. Gebruik de ruwe verzoektekst - niet een opnieuw geserialiseerd JSON-object - anders komt de HMAC niet overeen. Het ondertekeningsgeheim wordt eenmalig uitgegeven wanneer je de webhook URL instelt; roteer via het dashboard.

verifieer-handtekening.js
// Node.js / Express-voorbeeld
const crypto = nodig hebben("crypto");

app.post("/webhook".", express.ruw({type: "application/json" }), (req, res) => {
  const handtekening = req.headers["x-fabrixa-handtekening"."];
  const [tPart, v1Part] = handtekening.gesplitst(",");
  const timestamp = tPart.gesplitst("=")[1];
  const ontvangen = v1Part.gesplitst("=")[1];

  // Gebeurtenissen ouder dan 5 minuten afwijzen (herhalingsbeveiliging)
  als (Wiskunde.abs(Datum.nu() / 1000 - tijdstempel) > 300) terugkeren res.status(400).einde();

  const payload = `${timestamp}.${req.body.toString()}`;
  const verwacht = crypto
    .maakHmac("sha256", process.env.FABRIXA_WEBHOOK_SECRET)
    .update(springlading)
    .samenvatting("hex");

  als (!crypto.timingSafeEqual(Buffer.van(ontvangen), Buffer.van(verwacht)) {
    terugkeren res.status(401).einde();
  }

  // Handtekening geldig - de gebeurtenis verwerken
  const gebeurtenis = JSON.parse(req.body);
  handleEvent(event);
  res.status(200).einde();
});

Gelijkwaardige voorbeelden voor Python (Flask), PHP, Ruby en Go staan in de map scripts van de Postman verzameling. timingSafeEqual belangrijk - gebruik geen gelijkheid van tekenreeksen, dit is kwetsbaar voor timingaanvallen.

TERUGHAALBELEID

Exponentiële backoff tot 24 uur.

Webhook levering is op zijn minst eenmalig. Als uw eindpunt 5xx retourneert of een time-out heeft (10s timeout), proberen we het opnieuw op een exponentieel backoff schema voor maximaal 24 uur. Na 24 uur falen belandt het evenement in een wachtrij met dode letters die u handmatig opnieuw kunt afspelen.

ONMIDDELLIJK

Eerste levering + opnieuw proberen 1

Eerste levering bij gebeurtenis. Als 5xx of time-out, 30 seconden later opnieuw proberen.

ACHTERUIT

Herhalingen 2-8, exponentieel

60s → 5min → 30min → 2h → 6h → 12h → 24h. Bij elke nieuwe poging wordt er langer gewacht.

DEAD-LETTER

Na 24 uur storing

Gebeurtenis verplaatst naar wachtrij voor dode letters. Handmatig opnieuw afspelen via dashboard of POST /v1/webhooks/replay/:levering_id.

ORDER.MISLUKT GEBEURTENIS

Gestructureerde foutredenen voor inschakellogica.

De operationeel belangrijkste gebeurtenis. De nuttige lading omvat een stabiele error.code string - veilig om in te schakelen voor geautomatiseerde routering, het aanmaken van tickets of berichten voor eindklanten.

order.mislukt
{
  "gebeurtenis":     "order.mislukt",
  "order_id":  "ord_8e6f4b2a",
  "order_ref": "shopify-1042",
  "timestamp": "2026-05-13T09:14:22Z",
  "data": {
    "fout": {
      "code":    "kunstwerk_onbereikbaar",
      "bericht": "GET op artwork_url mislukt (timeout 30s) na 3 pogingen",
      "opnieuw proberen": Echt,
      "context": {
        "artwork_url": "https://cdn.yourbrand.com/art/drop-001.png"
      }
    }
  }
}

# Algemene fout.code waarden:
# artwork_unreachable - je URL voor het kunstwerk heeft niet gereageerd
# artwork_invalid_format - kon het bestand niet ontleden (probeer PNG / vector PDF)
# artwork_resolution_low - DPI te laag voor het gekozen product
# address_invalid - adres ontvanger niet gevalideerd
# stof_niet beschikbaar - stofbasis >7 dagen niet op voorraad
# payment_method_failed - facturering in bestand geweigerd
# compliance_flag - order gemarkeerd door nalevingscontrole
TESTEN

Trigger voorbeeldgebeurtenissen zonder echte orders.

POST /v1/webhooks/test stuurt een synthetische gebeurtenis van elk type naar je geregistreerde webhook URL. Nuttig voor het testen van uw handler voordat u echte orders plaatst, of voor het verifiëren van van een nieuw eindpunt na een implementatie.

Sandbox webhooks leveren aan je sandbox URL. Gebruik een tunneltool (ngrok, Cloudflare Tunnel) om sandbox webhooks naar localhost te wijzen tijdens ontwikkeling.

POST /v1/webhooks/test
krul -X POST $BASE_URL/v1/webhooks/test \
  -H "Autorisatie: Bearer $KEY" \
  -H "Inhoudstype: toepassing/json"." \
  -d '{
    "gebeurtenis": "order.verzonden",
    "sample_order_id": "monster"
  }'

# 200 OK
{
  "delivery_id": "del_test_94kQ",
  "posted_to":   "https://your-tunnel.ngrok.io/webhook",
  "status":      "in de wachtrij"
}
Fabrixa webhooks instellen - real-time ordergebeurtenissen voor je platform
UW WEBHOOK REGISTREREN

Stel de URL één keer in. Wij zorgen voor de levering.

Eén webhook-URL per account, alle gebeurtenistypen werken eraan. Filter op de evenement veld in je handler. Instellen via de integratiegids.

Winkelwagen (0 artikelen)

Maak je account aan