Webhooks

Webhooks ontvangen realtime events via HTTP POST naar een door jou geconfigureerde URL. Dezelfde events zijn ook beschikbaar via SSE. Webhooks zijn per organisatie geconfigureerd - elke organisatie heeft zijn eigen webhooks.

Beheer

Zie de OpenAPI-specificatie voor volledige request- en response-schema's.

Webhook aanmaken

POST /api/orgs/org_abc123/webhooks
Content-Type: application/json
x-api-key: tkn_xxx
X-Tillor-Org-Id: org_abc123

{
  "url": "https://jouw-server.com/webhooks/tillor",
  "subscribedEventKeys": ["invoice:created", "invoice:paid", "customer:updated"],
  "enabled": true
}

• url - HTTPS-endpoint die POST-requests accepteert
• subscribedEventKeys - Array van event keys of ["*"] voor alle events. De volledige lijst staat in Tillor onder Instellingen → Ontwikkelaars bij het aanmaken van een webhook.
• enabled - true om levering in te schakelen

Webhook-payload

Elke webhook-levering is een POST met:

Headers:

• Content-Type: application/json
• X-Webhook-Event-ID - stabiele unieke ID voor deze logische levering (zelfde waarde bij retries)
• X-Webhook-Signature - HMAC-SHA256 handtekening van de body, formaat sha256=<hex> (zie Handtekening verifiëren)

Body:

{
  "event": "invoice:created",
  "data": {},
  "timestamp": 1735689600000
}

Zie Voorbeelden voor volledige payload-voorbeelden.

Handtekening verifiëren

Elke webhook bevat een eigen signing secret (64 hex-karakters, getoond bij aanmaken in Instellingen → Ontwikkelaars). Tillor ondertekent elke POST met die secret zodat jij kunt verifiëren dat het verzoek écht van Tillor komt en dat de body niet is aangepast.

Hoe Tillor ondertekent:

1. Bereken HMAC-SHA256(signingSecret, raw_request_body) (lowercase hex).
2. Stuur dat als X-Webhook-Signature: sha256=<hex>.

Hoe jij verifieert:

1. Lees de ruwe request-body (vóór JSON-parsen — anders matcht de hash niet).
2. Bereken zelf HMAC-SHA256(signingSecret, raw_body) in hex.
3. Vergelijk met de waarde achter sha256= uit de X-Webhook-Signature header met een constant-time vergelijking.

import crypto from "node:crypto";

function verifyTillorWebhook(rawBody, headerSignature, signingSecret) {
  const expected = crypto.createHmac("sha256", signingSecret).update(rawBody).digest("hex");
  const received = headerSignature.replace(/^sha256=/, "");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(received, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Leveringsgedrag en retries

• Antwoord met een 2xx-status om succes te bevestigen.
• Bij een mislukte levering (niet-2xx, netwerkfout of geblokkeerd doel) probeert Tillor de levering automatisch opnieuw met steeds langere tussenpozen. Elke poging hergebruikt dezelfde payload, dezelfde handtekening en hetzelfde event-id (idempotent).

• Slaagt één van de pogingen (2xx) → de levering is afgerond.
• Slaagt ook poging 10 (na 24u) niet → de levering wordt definitief gemarkeerd als mislukt en niet verder geprobeerd.
• Wordt de webhook intussen uitgeschakeld, dan stopt Tillor met opnieuw proberen.

Event types

Event keys gebruiken het formaat entity:action of entity:subresource:action. Hieronder een selectie; de volledige lijst staat in Tillor onder Instellingen → Ontwikkelaars - in Tillor: Instellingen → Ontwikkelaars (per organisatie) bij het aanmaken van een webhook.

Webhooks vs SSE

Gerelateerd

• OpenAPI - Volledige API-specificatie
• HTTP API - REST API en API-sleutels
• SSE - Zelfde events via Server-Sent Events