Webhooks (admin)

FixControl handles two kinds of webhooks:

• Inbound — providers (Slack, GitHub, GitLab, Bitbucket, Office 365) deliver events to FixControl. Configured per integration.
• Outbound — your own systems subscribe to FixControl events. Configured under Settings → Integrations → Outbound webhooks.

User-facing setup steps for outbound webhooks live in the user guide. This page is the operational view: how delivery behaves and how to debug failed deliveries.

Inbound: signature verification

Every inbound webhook is signed by the provider; FixControl verifies before accepting. Mismatched signatures return 401 and the request is dropped — it is never processed.

Signing secrets are stored encrypted. Rotation is supported — the old secret keeps verifying for a 60-second grace window so in-flight deliveries don't fail mid-rotation.

Inbound: processing & retry

Verified webhook payloads are queued and processed asynchronously. The provider gets a 200 response right away; FixControl does the actual work in the background. If processing fails (transient outage, downstream timeout), the job retries with exponential backoff up to 6 attempts before being marked failed.

Outbound: delivery model

When a FixControl event matches one of your outbound webhook subscriptions, a delivery is enqueued and POSTed to your URL:

event fired
  → match subscriptions (by tenant + event filter)
  → for each match: enqueue delivery
  → POST to URL, record status + duration

Successful deliveries (HTTP 2xx) close out. Non-2xx or no response within 10 seconds re-tries with backoff — three attempts total:

retry 1   ~1s after the first attempt
retry 2   ~5s after the second

After the last retry the delivery is marked failed and stops. Failed deliveries are visible per webhook under Settings → Integrations → Outbound webhooks → [your webhook] → Deliveries, and an admin can replay any of them by clicking Replay.

Operational signals

The integrations health panel surfaces:

• Queue depth per provider — how many inbound events are waiting.
• Recent failures — last 100 failed deliveries (inbound or outbound).
• Reconnect required — integrations whose tokens expired and need re-consent.
• Time since last event — flags a channel that's silent unexpectedly long.

A red dot on a tile means at least one of the above tripped a threshold. Click in for detail.

Common operational issues

Inbound webhook returns 401 every time. Signing secret mismatch. Check the secret in the provider's UI matches what FixControl shows on the integration page (the last 4 chars are visible). If the upstream secret was rotated, click Rotate signing secret in FixControl too.

Outbound deliveries succeed but the receiver doesn't process them. Almost always signature verification failing on the receiver. Confirm that the receiver computes HMAC-SHA256 over <timestamp>.<raw request body> — the t= value from the signature header, a dot, then the byte-for-byte body — not parsed JSON. See the user webhooks guide for a working verifier.

Subscriptions silently expired (Office 365). Microsoft Graph subscriptions live ~3 days and FixControl renews them on a schedule. If a renewal is missed and the subscription expires, the integration moves to Reconnect required. Reconnect from the integrations page — events that arrived during the gap are not retroactive (Microsoft doesn't queue them server-side).

FAQ

Can I disable retries for a specific webhook? Set its max attempts to 1 in the webhook detail page. After the first failure it goes straight to failed, no retries.

Can I see the exact body that was sent? Yes. Each delivery row stores the request body and the response status / body (truncated to 4KB). Useful for debugging mismatches.

Are webhook secrets rotated automatically? No — rotation is admin-triggered. We don't auto-rotate because some receivers can't handle a rotation without coordination, and we'd rather have a clear admin action than a silent break.