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.

Jun 26, 2026

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

  1. Confirm the subscription: GET /v1/webhooks/{webhook} and check that is_active is true and your event is in events.
  2. Review the delivery logs returned by that same endpoint: if there are attempts with 4xx/5xx response codes, the problem is on your server (not Omnifox).
  3. Return 2xx fast: your endpoint must reply 200 within timeout_seconds. If it's slow, Omnifox counts it as a failure and retries up to retry_count.
  4. Public URL over HTTPS: the URL must be reachable from the internet with a valid certificate. localhost or private IPs receive no deliveries.
  5. Verify the signature correctly: compute HMAC-SHA256(body, signing_secret) and compare it to X-Omnifox-Signature. If you rotated the secret (rotate-secret), update the value on your server.
  6. The event name is exact: use the catalog names exactly (e.g. message.received, not message_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 200 should appear.
  • API: GET /v1/teams with your token should return 200.
  • 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

Was this helpful?

Related articles

Message us on WhatsApp