Webhooks

LokaalKabaal stuurt events naar elk retailer-endpoint dat je registreert (Zapier catch-hook, Slack incoming webhook, self-hosted HTTP). Elk event wordt HMAC-SHA256 gesigned met je gedeelde secret zodat je kunt verifiëren dat een payload écht van ons komt.

Event-types

Voorbeeld payload

POST https://jouw-endpoint.nl/hook
Content-Type: application/json
X-LokaalKabaal-Signature: <hex-hmac-sha256>
X-LokaalKabaal-Event: scan.registered

{
  "type": "scan.registered",
  "retailerId": "c3f2a7d1-...",
  "campagneId": "8fe34bb2-...",
  "code": "ABCD1234",
  "postcode": "3512",
  "stad": "Utrecht",
  "at": "2026-04-28T14:07:22.000Z"
}

Signatuur verifiëren

// Node.js
import crypto from 'crypto';

function verify(body, provided, secret) {
  const expected = crypto.createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(provided, 'hex'),
  );
}

Onze signing-helper uit lib/webhook-outbox gebruikt precies dit patroon (signWebhookBody, verifyWebhookSignature), dus dezelfde logica werkt aan beide kanten.

Retry-schema

Als je endpoint geen 2xx teruggeeft, retryen we volgens exponential backoff: 30s -> 2min -> 8min -> 30min -> 2h, daarna geven we op en sturen een dagelijkse samenvatting naar je account-email. Handige 5xx-response codes om op te letten:

• 200/204 -- geaccepteerd, geen retry
• 4xx -- client error, we retryen nog één keer en markeren je endpoint als unhealthy
• 5xx / timeout -- volledige retry-schedule