Custom headers, retries, circuit breaker and rotating the signing secret

Configure custom headers, define the retry policy and circuit breaker, and safely rotate the signing secret of your Omnifox webhooks.

Jun 26, 2026

Watch this step in the video · Signing secret, retries and headers

What this configuration is for

Once a webhook works, the next step is making it robust and secure: add authentication headers for your endpoint, control how Omnifox retries on failure, protect your system with a circuit breaker, and rotate the signing secret when needed. All of it lives in the webhook editor.

How Omnifox signs each delivery

On every POST, Omnifox includes these headers:

  • Content-Type: application/json
  • X-Omnifox-Event: the event type (e.g. message.received)
  • X-Omnifox-Delivery-Id: a unique delivery identifier
  • X-Omnifox-Attempt: the attempt number
  • User-Agent: Omnifox-Webhook/1.0
  • X-Omnifox-Signature: sha256=<hmac> and X-Omnifox-Timestamp

The signature is an HMAC-SHA256 of the raw body computed with your signing secret. On your server, recompute the HMAC with the same secret and compare it to X-Omnifox-Signature to confirm the request came from Omnifox and wasn't tampered with.

Custom headers

If your endpoint requires its own authentication (a token, an API key, etc.), add it as a header:

  1. Open Webhooks and click Edit on the webhook.
  2. Scroll to Custom headers and click Add header.
  3. Type the name (e.g. Authorization) and the value (e.g. Bearer my-token).
  4. Repeat per header and click Save changes.

These headers are sent on every delivery in addition to the signature headers.

Retry policy

In the Retry policy section you define what happens when a delivery fails:

  • Strategy:
    • Exponential (recommended): growing backoff 2s → 4s → 8s → 16s → 32s … (max 5 min).
    • Linear: 60s between attempts.
    • No retries: fails immediately.
  • Max retries: how many additional attempts are made (0 = none).
  • Circuit breaker threshold: consecutive failures before the circuit "opens".

The panel shows a visual Retry schedule with the delay of each attempt.

Circuit breaker

The circuit breaker protects both Omnifox and your endpoint: if too many consecutive failures pile up (the threshold), the circuit goes Open and deliveries pause for a few minutes. It then becomes Half-open and tries one delivery: if it succeeds, it returns to Closed; if it fails, it reopens. This avoids hammering a server that is down. You can view the state and Force close circuit breaker from the webhook detail page.

Rotating the signing secret

Rotate the secret if you suspect it leaked or as periodic hygiene:

  1. In the Webhooks list, use the Regenerate secret button, or open Edit and click Regenerate in the Signing secret card.
  2. Confirm. Heads up: your integration will stop validating signatures until you update the secret on your server.
  3. Copy the new secret and replace it in your code just before (or right after) regenerating to minimize the failure window.

If it doesn't work

  • Invalid signatures after rotating: your server still uses the old secret; update it.
  • The circuit breaker opens on its own: your endpoint is returning errors; check the Delivery history and HTTP codes.
  • Your API key doesn't arrive: confirm you saved it under Custom headers and clicked Save changes.

Tip: use the Exponential strategy with a moderate circuit breaker threshold (e.g. 10) to tolerate brief outages without overloading your system.

Related articles

Was this helpful?

Related articles

Message us on WhatsApp