Troubleshooting: webhook not firing, API auth and OAuth errors
How to diagnose webhooks that don't fire, 401/403 errors on the REST API and OAuth connection failures in integrations.
Watch this step in the video · Troubleshooting
Note: the OAuth gallery connectors (Gmail, Outlook, HubSpot, Salesforce, Shopify, Google Sheets, Google Meet, Calendly, Stripe Payments, Zoom, Microsoft Teams, DocuSign, Dropbox Sign, PandaDoc and Notion) are coming soon: in Settings → Integrations their cards show as "Coming soon" and they can't be connected yet. The OAuth section of this guide will apply once they're available. Webhooks and the REST API do work today (from the Crece plan); to connect other tools in the meantime, use n8n, Make or Zapier.
What this covers
This guide fixes the three most common issues when integrating Omnifox via API: a webhook that receives no events, authentication errors on REST API v1, and OAuth failures when connecting integrations (Gmail, Outlook, HubSpot, etc.).
The webhook receives no events
- Confirm the subscription:
GET /v1/webhooks/{webhook}and check thatis_activeistrueand your event is inevents. - Review the delivery logs returned by that same endpoint: if there are attempts with
4xx/5xxresponse codes, the problem is on your server (not Omnifox). - Return 2xx fast: your endpoint must reply
200withintimeout_seconds. If it's slow, Omnifox counts it as a failure and retries up toretry_count. - Public URL over HTTPS: the URL must be reachable from the internet with a valid certificate.
localhostor private IPs receive no deliveries. - Verify the signature correctly: compute
HMAC-SHA256(body, signing_secret)and compare it toX-Omnifox-Signature. If you rotated the secret (rotate-secret), update the value on your server. - The event name is exact: use the catalog names exactly (e.g.
message.received, notmessage_received).
API auth errors (401 / 403)
- 401 Unauthorized: the Bearer token is missing, mistyped or revoked. Send
Authorization: Bearer 123_aBc...(the full token value;omf_is only the prefix shown in the list) and verify the key in Settings → API Keys. - 403 Forbidden: the token is valid but points to another workspace. Each token is scoped to a single workspace; generate a token for the right workspace or pass the matching
workspace_id. - 404 on a resource that exists: the ID likely belongs to another workspace (scoping hides it) rather than being missing.
- 422 Validation error: required body fields are missing; the response lists the invalid fields.
- 429 Too Many Requests: you exceeded your plan's per-minute request limit (e.g. 1,200 per minute on Crece; see API rate limits and quota headers); apply exponential backoff.
OAuth failures when connecting integrations (once available)
- The card shows "Coming soon": that connector isn't enabled in Omnifox yet; it's not an error on your account. In the meantime, use n8n, Make or Zapier.
- "Select a workspace before connecting": pick the workspace in the top selector and retry.
- "The OAuth session expired. Try again": the flow took too long between Connect and the callback; restart it from the card.
- redirect_uri_mismatch (Google/Microsoft): the callback URL registered in the provider app doesn't match Omnifox's. Ask the admin to align the Authorized redirect URIs.
- Connects but stops syncing (Gmail): no refresh token was issued; Disconnect and Connect again to force a fresh consent.
Verify
- Webhook: trigger a real event (create a contact) and check the delivery logs — a
200should appear. - API:
GET /v1/teamswith your token should return200. - OAuth: the integration card should read Connected with the account.
Tips
- Always log the raw body of each incoming webhook: it makes signature comparison easy.
- Keep one API token per external system; that way you can revoke one without breaking the rest.
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.