Webhooks: orderupdates automatisch ontvangen

Hoe werken webhooks?

Je geeft ons een https-url van je eigen server. Bij elke gebeurtenis sturen we daar een POST-verzoek naartoe met een JSON-bericht. Je server antwoordt met een 2xx-status, en dan weten wij dat het bericht is aangekomen.

• X-Printen-Event: het soort event, bijvoorbeeld order.shipped.
• X-Printen-Delivery: een id van deze aflevering. Handig in je logs.
• X-Printen-Timestamp: het tijdstip van verzenden, in seconden sinds 1970 (Unix-tijd).
• X-Printen-Signature: de handtekening (v1= gevolgd door een hex-code), waarmee je controleert dat het bericht echt van ons komt.

Hoe voeg je een endpoint toe?

1. 1

   Open het tabblad

   Ga in je dashboard naar Webhooks.

2. 2

   Vul je url in

   Vul bij Url (https) het adres van je eigen server in, bijvoorbeeld https://jouwdomein.nl/printen-webhook.

3. 3

   Kies de events

   Vink aan welke events je wilt ontvangen. Standaard staan order.shipped, order.payment_failed en order.awaiting_funds aangevinkt.

4. 4

   Voeg de webhook toe

   Klik op Webhook toevoegen. Je ziet nu het geheim, met de melding Bewaar dit geheim nu. Je ziet het maar één keer.

5. 5

   Bewaar het geheim

   Zet het geheim direct in de configuratie van je server, bijvoorbeeld als omgevingsvariabele. Je hebt het nodig om de handtekening te controleren.

Je kunt een endpoint ook via de API toevoegen met POST /webhooks. Laat je events weg of stuur je een lege lijst, dan ontvang je alle events. Het geheim staat alleen in dit ene antwoord.

curl -X POST https://www.printen.eu/api/reseller/v1/webhooks \
  -H "Authorization: Bearer prk_live_..." -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/printen-webhook","events":["order.shipped","order.delivered"]}'

{
  "data": {
    "id": "WEBHOOK_ID",
    "url": "https://example.com/printen-webhook",
    "events": ["order.shipped", "order.delivered"],
    "allEvents": false,
    "active": true,
    "createdAt": "2026-10-10T09:00:00.000Z",
    "updatedAt": "2026-10-10T09:00:00.000Z",
    "secret": "WEBHOOK_SECRET"
  }
}

• De url moet https gebruiken en publiek bereikbaar zijn. Adressen als localhost, interne netwerkadressen en namen die eindigen op .local, .internal of .lan worden geweigerd.
• Je kunt maximaal 10 endpoints per account hebben.
• Elk endpoint heeft een eigen geheim.

Welke events zijn er?

Hoe ziet een bericht eruit?

Elk bericht heeft dezelfde opbouw. Hieronder een voorbeeld van order.shipped.

{
  "id": "EVENT_ID",
  "type": "order.shipped",
  "created": "2026-10-10T14:32:05.000Z",
  "data": {
    "order": {
      "id": "ORDER_ID",
      "orderNumber": "RS-3F9A1C7B2E",
      "externalOrderId": "1001",
      "externalOrderNumber": "1001",
      "state": "SUBMITTED",
      "status": "SHIPPED",
      "tracking": {
        "code": "3SABCD1234567",
        "url": "https://example.com/track/3SABCD1234567"
      },
      "items": [
        {
          "productId": "PRODUCT_ID",
          "name": "Poster",
          "quantity": 1,
          "options": { "size": "A2" }
        }
      ]
    }
  }
}

Hoe controleer je de handtekening?

Iedereen kan een verzoek naar je url sturen. Controleer daarom bij elk bericht de handtekening voordat je er iets mee doet. De handtekening is een HMAC-SHA256 met het geheim van je endpoint.

1. 1

   Lees de headers

   Haal X-Printen-Timestamp en X-Printen-Signature uit het verzoek.

2. 2

   Controleer de tijd

   Wijs het bericht af als de timestamp meer dan 5 minuten (300 seconden) afwijkt van de huidige tijd. Zo kan niemand een oud bericht opnieuw afspelen.

3. 3

   Bereken de verwachte handtekening

   Bereken een HMAC-SHA256 met je geheim over de tekst timestamp.rawBody: de timestamp, een punt en daarna de ruwe body. Zet er v1= voor.

4. 4

   Vergelijk veilig

   Vergelijk de uitkomst met X-Printen-Signature met een vergelijking die altijd even lang duurt (constant time). Komen ze niet overeen, antwoord dan met 401 en verwerk niets.

import crypto from 'node:crypto';

export function verifyPrintenWebhook(rawBody, headers, secret) {
  const timestamp = headers['x-printen-timestamp'];
  const signature = headers['x-printen-signature'] || '';
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = 'v1=' + crypto.createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`).digest('hex');
  return signature.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

<?php
function verify_printen_webhook(string $rawBody, string $timestamp, string $signature, string $secret): bool {
    if (abs(time() - (int) $timestamp) > 300) return false;
    $expected = 'v1=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
    return hash_equals($expected, $signature);
}

import hashlib, hmac, time

def verify_printen_webhook(raw_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    if abs(time.time() - int(timestamp)) > 300:
        return False
    expected = "v1=" + hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Valkuil: controleer op de ruwe body

De handtekening is berekend over de body precies zoals wij hem versturen, byte voor byte. Veel frameworks lezen de body automatisch als JSON. Zet je die JSON daarna weer om naar tekst, dan kunnen spaties, volgorde of tekens net anders zijn, en klopt de handtekening niet meer.

import express from 'express';
import { verifyPrintenWebhook } from './verify-printen-webhook.js';

const app = express();

// express.raw (not express.json) keeps the body exactly as it was sent
app.post('/printen-webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  const rawBody = req.body.toString('utf8');
  if (!verifyPrintenWebhook(rawBody, req.headers, process.env.PRINTEN_WEBHOOK_SECRET)) {
    return res.status(401).send('invalid signature');
  }
  const event = JSON.parse(rawBody);
  await saveEventForProcessing(event); // store first, process later
  res.status(200).send('ok');
});

• PHP: lees de body met file_get_contents("php://input"), niet met $_POST.
• Python (Flask): gebruik request.get_data() voor de ruwe bytes, niet request.json.
• Next.js (App Router): gebruik await request.text() en pas daarna JSON.parse.

Wat als je endpoint niet antwoordt?

Een aflevering is geslaagd als je binnen 10 seconden antwoordt met een 2xx-status. Elke andere uitkomst telt als mislukt: een time-out, een foutstatus, maar ook een doorverwijzing (3xx). Dan proberen we het opnieuw volgens dit schema.

Na de tiende poging geven we het voor dat event op. Je endpoint wordt nooit automatisch uitgeschakeld: nieuwe events blijven we gewoon sturen.

Dubbele en ongeordende events verwerken

Door herhalingen kan hetzelfde event meer dan één keer binnenkomen, en events kunnen in een andere volgorde aankomen dan ze zijn ontstaan. Bouw je verwerking daarop.

• Ontdubbel op `id`: bewaar de id van elk verwerkt event. Komt dezelfde id nog eens binnen, antwoord dan met 2xx en doe verder niets.
• Let op de volgorde met `created`: heb je al een nieuwer event voor deze order verwerkt, overschrijf dan geen nieuwere status met een oudere.
• Zet geen status terug: komt order.shipped binnen na order.delivered, laat de order dan op afgeleverd staan.
• Twijfel je, vraag de order op: met GET /orders/{id} krijg je altijd de actuele stand.

Hoe test je je webhook?

1. 1

   Zet je endpoint klaar

   Zorg dat je url publiek bereikbaar is via https. Werk je lokaal, gebruik dan een tunnelservice die een publieke https-url doorstuurt naar je eigen computer.

2. 2

   Voeg het endpoint toe

   Voeg het toe bij Webhooks en vink order.created, order.submitted en order.cancelled aan (of laat de events weg via de API om alles te ontvangen).

3. 3

   Plaats een sandboxorder

   Plaats met een testsleutel (prk_test_) een order via de API. Binnen een paar minuten ontvang je order.created en order.submitted (met test in data).

4. 4

   Annuleer de testorder

   Annuleer de order met POST /orders/{id}/cancel. Je ontvangt dan order.cancelled.

5. 5

   Controleer je logs

   Kijk of de handtekening klopt, of je 2xx teruggaf en of een herhaald bericht met dezelfde id netjes werd genegeerd.

Problemen oplossen