Webhooks

Met uitgaande webhooks duw je FixControl-events naar je eigen systemen — een Slack-notifier, een facturatieservice, een statuspagina of een intern dashboard. Jij kiest de events en geeft een URL op; FixControl ondertekent elke delivery en probeert opnieuw bij falen.

Een webhook aanmaken

1. Open Settings → Integraties → Uitgaande webhooks.
2. Klik Webhook toevoegen.
3. Vul in:

- URL — https://.... Verplicht HTTPS in productie. - Events — kies welke events geleverd worden (zie hieronder). Een lege lijst betekent alle events voor je tenant. - Beschrijving — voor je eigen administratie.

1. Klik Aanmaken. Het signing-secret wordt één keer getoond — kopieer het direct naar je secret store. Daarna kun je het niet meer terughalen, alleen roteren.

Events

Elke delivery heeft JSON met een event-veld. De events die er nu zijn:

Abonneer alleen op events die je nodig hebt — minder filters betekenen minder deliveries om af te handelen.

Payload-vorm

{
  "id": "evt_01HV9F...",
  "event": "patch.applied",
  "tenant": "acme",
  "occurred_at": "2026-05-03T10:14:22.512Z",
  "data": {
    "patch_id": "ptch_01HV...",
    "issue_id": "iss_01HU...",
    "pull_request_url": "https://github.com/acme/api/pull/4421"
  }
}

data verschilt per event, maar de envelope (id, event, tenant, occurred_at) ligt vast. Gebruik id voor idempotency: als je een delivery met dezelfde id al hebt verwerkt, negeer dan het duplicaat.

Signature verifiëren

Elke delivery wordt ondertekend met HMAC-SHA256 en het secret van je webhook.

Headers per delivery:

• X-FixControl-Signature: sha256=<hex> — HMAC over de raw request-body.
• X-FixControl-Timestamp: <unix-seconds> — verzendtijd.
• X-FixControl-Event: <event-name> — kopie van het event-veld.
• X-FixControl-Delivery: <id> — gelijk aan id in de body.

Verificatiestappen:

1. Lees de raw request-body — bytes, geen geparste JSON.
2. Bereken sha256_hex(hmac(secret, body)).
3. Vergelijk met de waarde achter sha256= met een constant-time compare.
4. Wijs af als de timestamp meer dan 5 minuten afwijkt — dat is het replay-venster.

Voorbeeld (Node.js):

import { createHmac, timingSafeEqual } from "crypto";

function verify(req, secret) {
  const sig = req.headers["x-fixcontrol-signature"]?.split("=")[1];
  const ts  = parseInt(req.headers["x-fixcontrol-timestamp"], 10);
  if (!sig || Math.abs(Date.now() / 1000 - ts) > 300) return false;
  const expected = createHmac("sha256", secret).update(req.rawBody).digest("hex");
  return sig.length === expected.length &&
         timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Wijs elk request af waar verificatie faalt. Vertrouw nooit een webhook op basis van URL alleen — een URL is geen secret.

Retries

Als je endpoint een non-2xx-status teruggeeft (of niet binnen 10 seconden antwoordt), probeert FixControl het opnieuw met exponentiële backoff:

poging 1   direct
poging 2   ~30 seconden later
poging 3   ~2 minuten later
poging 4   ~10 minuten later
poging 5   ~1 uur later
poging 6   ~6 uur later

Na de laatste poging staat de delivery op failed en stopt het opnieuw proberen. Failed deliveries verschijnen onder Settings → Integraties → Uitgaande webhooks → [jouw webhook] → Deliveries en kun je handmatig opnieuw afspelen.

Testen

De webhook-detailpagina heeft een Stuur test-event-knop. Daarmee verstuur je een minimaal webhook.test-payload naar je endpoint zodat je je verificatie + handler kunt testen voordat er echte events gaan vuren.

Operationele aandachtspunten

• Tenant-isolatie — een webhook ontvangt alleen events voor de tenant waar hij in is aangemaakt.
• Pauzeren zonder verwijderen — zet de Active-toggle uit om deliveries tijdelijk te stoppen.
• Roteer het secret — klik Roteer secret. Het nieuwe secret wordt één keer getoond; het oude blijft 60 seconden ondertekenen voor in-flight deliveries.
• Verwijderen — soft-delete; deliveries die al in de wachtrij stonden kunnen nog opnieuw proberen tot hun retry-budget op is, maar de webhook is direct uit de UI weg.

Veelgestelde vragen

Kan ik webhooks van Slack/GitHub via FixControl ontvangen? Dat zijn inkomende webhooks. Die configureer je per integratie aan de admin-kant — zie de admin-handleiding voor webhooks (Engelstalig).

Mijn endpoint zit achter auth. Hoe laat ik FixControl door? Outbound auth-headers (Basic, bearer) worden nog niet ondersteund — verifieer in plaats daarvan de HMAC. Moet het verkeer over een privé-netwerk: zet er een publieke proxy voor die geverifieerde requests doorzet.

In welk formaat is de signature? Hex-encoded HMAC-SHA256 over de raw request-bytes, met prefix sha256=. Dezelfde keuze als Stripe en GitHub.