Best practices: reliable webhooks and scalable integrations
How to build webhooks that never drop or duplicate events: HMAC signing, idempotency, retries and fast acknowledgement.
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
- Go to Settings → Webhooks and click New webhook.
- Paste the target URL (always HTTPS).
- Pick the events you need:
message.received,message.sent,conversation.created,conversation.closed,contact.created,contact.updated. Subscribe only to what you'll use. - Copy and store the signing secret (
whsec_…) in your vault. Omnifox signs every delivery with it. - Set the retry strategy (
exponentialrecommended) and the max retries (default 5). - 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
Related articles
-
How to connect integrations and external apps
Connect Omnifox with your favorite tools from the integrations catalog in just a few steps.
-
Integrations and API complete guide
Integrations and API in depth, in 30 chapters: API keys, real calls, signed webhooks, n8n, MCP and SDKs, all really working.
-
Connecting Omnifox to Azur, Siigo, Alegra, QuickBooks or another accounting system or ERP
Omnifox doesn't have a native connector for accounting systems or ERPs today. Here's how to connect them anyway with workflows, the HTTP node, n8n, Make, Zapier or the API, with examples.
-
Generate and use API keys and webhooks
Create API keys to access Omnifox programmatically and set up webhooks to receive real-time events.
-
Getting started with integrations (webhook / OAuth / API key)
Connect Omnifox with your other tools: what's available today, what's coming soon, and when to use a webhook, an OAuth connection or an API key.