Webhooks (beheer)

FixControl behandelt twee soorten webhooks:

Inkomend — providers (Slack, GitHub, GitLab, Bitbucket, Office 365) leveren events af bij FixControl. Per integratie geconfigureerd.
Uitgaand — je eigen systemen abonneren zich op FixControl-events. Geconfigureerd onder Settings → Integrations → Outbound webhooks.

Stappen voor de eindgebruiker bij uitgaande webhooks staan in de user guide. Deze pagina is de operationele kijk: hoe delivery zich gedraagt en hoe je gefaalde deliveries debugt.

Inkomend: signature-verificatie

Elke inkomende webhook is door de provider gesigneerd; FixControl verifieert vóór accepteren. Mismatched signatures geven 401 en de request wordt gedropped — die wordt nooit verwerkt.

Provider	Header	Algoritme
GitHub	`X-Hub-Signature-256`	HMAC-SHA256 over raw body
GitLab	`X-Gitlab-Token`	Token-equality (constant time)
Bitbucket	`X-Hub-Signature`	HMAC-SHA256 over raw body
Slack	`X-Slack-Signature` + `X-Slack-Request-Timestamp`	HMAC-SHA256 over `v0:<ts>:<body>`
Microsoft Teams	`Authorization: Bearer <jwt>`	JWT gesigneerd door Microsoft, gevalideerd tegen hun public keys
Office 365	client-state + JWT-validatie	Per-subscription gevalideerd

Signing secrets worden versleuteld opgeslagen. Rotatie wordt ondersteund — het oude secret blijft 60 seconden valideren als grace-window, zodat in-flight deliveries niet mid-rotation falen.

Inkomend: verwerking & retry

Geverifieerde webhook-payloads worden in een queue gezet en asynchroon verwerkt. De provider krijgt binnen 100ms een 200 terug; FixControl doet het eigenlijke werk op de achtergrond. Faalt verwerking (transient uitval, downstream-timeout), dan retryt de job met exponentiële backoff tot 6 pogingen voordat 'ie als failed gemarkeerd wordt.

Uitgaand: delivery-model

Lijst van uitgaande webhooks met één geconfigureerde webhook en een recente delivery-rij

Wanneer een FixControl-event matcht met één van je outbound webhook-subscriptions, wordt een delivery in de wachtrij gezet en met POST naar jouw URL gestuurd:

event vuurt af
  → match subscriptions (op tenant + event-filter)
  → per match: enqueue delivery
  → POST naar URL, registreer status + duur

Geslaagde deliveries (HTTP 2xx) sluiten af. Niet-2xx of geen response binnen 10 seconden re-tryt met backoff:

retry 1   ~30s
retry 2   ~2m
retry 3   ~10m
retry 4   ~1u
retry 5   ~6u

Na de laatste retry wordt de delivery failed gemarkeerd en stopt. Failed deliveries zijn per webhook zichtbaar onder Settings → Integrations → Outbound webhooks → [jouw webhook] → Deliveries, en een admin kan elke replay-en met Replay.

Operationele signalen

Het integrations health panel toont:

Queue depth per provider — hoeveel inkomende events wachten.
Recente failures — laatste 100 gefaalde deliveries (inkomend of uitgaand).
Reconnect required — integraties waarvan de tokens expired zijn en re-consent nodig hebben.
Tijd sinds laatste event — flagt een kanaal dat onverwacht lang stil is.

Een rood bolletje op een tile betekent dat ten minste één van bovenstaande een drempel overschreed. Klik door voor detail.

Veelvoorkomende operationele issues

Inkomende webhook geeft elke keer 401. Signing secret-mismatch. Check of het secret in de UI van de provider matcht met wat FixControl op de integration-pagina toont (de laatste 4 chars zijn zichtbaar). Is het upstream-secret geroteerd, klik dan ook in FixControl op Rotate signing secret.

Uitgaande deliveries slagen, maar de ontvanger verwerkt ze niet. Vrijwel altijd signature-verificatie die op de ontvanger faalt. Bevestig dat de ontvanger de HMAC-SHA256 over de raw request body berekent, niet over geparsete JSON; de byte-voor-byte body is wat gesigneerd is.

Subscriptions stilletjes geëxpireerd (Office 365). Microsoft Graph-subscriptions leven ~3 dagen en FixControl vernieuwt ze op een schema. Wordt een renewal gemist en expireert de subscription, dan gaat de integratie naar Reconnect required. Reconnect via de integration-pagina — events die in de gap arriveerden zijn niet retroactief op te halen (Microsoft queuet ze niet server-side).

FAQ

Kan ik retries voor een specifieke webhook uitschakelen? Zet max attempts op 1 op de webhook-detailpagina. Na de eerste failure gaat 'ie direct naar failed, geen retries.

Kan ik de exacte body zien die gestuurd is? Ja. Elke delivery-rij slaat de request body en de response status / body op (getrunceerd op 4KB). Handig voor debug-mismatches.

Worden webhook-secrets automatisch geroteerd? Nee — rotatie is admin-getriggerd. We auto-roteren niet omdat sommige ontvangers een rotatie niet aankunnen zonder coördinatie, en we liever een duidelijke admin-actie hebben dan een stille breuk.