Best practices: reliable webhooks and scalable integrations

How to build webhooks that never drop or duplicate events: HMAC signing, idempotency, retries and fast acknowledgement.

Jun 26, 2026

Watch this step in the video · Security best practices

What it's for

Omnifox webhooks push real-time events (messages, conversations and contacts) to your own system, so you don't have to poll the API. Done well, they're the backbone of a scalable integration; done poorly, they drop events or duplicate data. This guide collects the practices we recommend for production.

Requirements

  • A role with access to Settings → Webhooks (Developer API access).
  • A public HTTPS endpoint that answers fast (ideally < 5s).
  • The ability to verify HMAC-SHA256 signatures on your backend.

Steps

  1. Go to Settings → Webhooks and click New webhook.
  2. Paste the target URL (always HTTPS).
  3. Pick the events you need: message.received, message.sent, conversation.created, conversation.closed, contact.created, contact.updated. Subscribe only to what you'll use.
  4. Copy and store the signing secret (whsec_…) in your vault. Omnifox signs every delivery with it.
  5. Set the retry strategy (exponential recommended) and the max retries (default 5).
  6. Save and use Send test to fire a test.ping.

Verify

Omnifox signs the body with HMAC-SHA256 and sends it in the X-Omnifox-Signature header; the event type rides in X-Omnifox-Event. On your endpoint, recompute the HMAC of the raw body with your secret and compare in constant time. If it doesn't match, return 401. Check the delivery logs on the webhook detail page to confirm 2xx responses.

Best practices

  • Return 200 immediately, process in the background. Acknowledge in milliseconds and push heavy work to a queue. A slow endpoint triggers retries and duplicates.
  • Be idempotent. Treat every delivery as "at least once". Store the event/message ID and drop repeats — retries are normal.
  • Always verify the signature before trusting the payload. Never process a body without checking X-Omnifox-Signature.
  • Don't assume ordering. Events can arrive out of order; reorder by timestamp if your logic needs it.
  • Keep it granular. Point each integration at its own events instead of one giant catch-all webhook.
  • Rotate the secret periodically from the webhook list (Regenerate secret) and update your vault.

If it doesn't work

  • No events arriving: confirm the webhook is active and the URL returns 2xx; check the delivery logs.
  • Duplicates: expected because of retries. Implement idempotency by ID.
  • Invalid signature: make sure you sign the raw body (not a re-serialized JSON) with the exact secret.
  • Endless retries: your endpoint is returning 4xx/5xx or taking too long. Answer 200 fast.

Tip: pair webhooks (event push) with the REST API at /api/v1/* (on-demand pull) to reconcile state after your service has an outage.

Related articles

Was this helpful?

Related articles

Message us on WhatsApp