Skip to main content

​
Troubleshooting: Integration webhook receiver returns 503

Every inbound event from a CRM or telephony integration you connected — HubSpot, Salesforce, Calendly, Intercom, or the DIDWW address-verification callback — returns HTTP 503 and no event lands on your dashboard. The provider’s own dashboard shows the deliveries failing in a row. None of these receivers 503 on a bad signature — a signature mismatch returns 401. A 503 from a receiver means one thing: the receiver is fail-closed because its signing secret is not provisioned, and it is rejecting every event until the secret is set.

​
Receiver inventory

Five integration receivers share this fail-closed shape, with three distinct error codes: All five return the same 503 envelope:
Receivers are fail-closed on purpose: an unverifiable pre-auth endpoint must not ingest events it cannot attribute. A 503 (not 401) tells the provider to back off and retry on a longer schedule, and tells your monitoring “we are misconfigured,” not “someone sent a bad signature.”

​
Symptom triage — 503 vs 401 vs 422

Match the status code first; each class has a different owner:
  • 503 + WEBHOOK_DISABLED / WEBHOOK_NOT_PROVISIONED / WEBHOOK_SECRET_NOT_CONFIGURED — the receiver is the integration’s inbound endpoint and its secret is missing. Only the operator can set the secret; the provider delivery itself is fine.
  • 401 + INVALID_SIGNATURE — the secret IS set but the signature check failed (rotation drift, stale timestamp, raw-body mismatch). That is Webhook signature invalid, not this page.
  • 422 from a pass-through integration route — schema or permission errors on Orbit’s own outbound-dispatch or endpoint-creation routes; those are unrelated to receiver provisioning. See Webhook endpoint creation errors.
Confirm which receiver you are looking at from the path in the provider’s delivery log: .../integrations/webhooks/hubspot, .../salesforce, .../calendly, .../intercom, or the DIDWW address-verification callback URL.

​
Per-integration recovery

Set the secret the table above names, once. Do not loop the recovery step.

​
HubSpot

  1. Copy the client secret from the HubSpot app (Developer account → your app → Auth).
  2. Set DEVOTEL_HUBSPOT_CLIENT_SECRET in the API service environment and restart.
  3. Re-deliver one failed event from the HubSpot webhook settings; expect 200.

​
Salesforce

  1. Set DEVOTEL_SALESFORCE_WEBHOOK_HMAC_SECRET to the same HMAC secret the connected app signs with (the value chosen when the integration was installed).
  2. Restart the API service and re-deliver a test event from the Salesforce side.
  3. If 503 clears but the next delivery returns 401, the values disagree — re-check for trailing whitespace and re-run the install.

​
Intercom

  1. Copy the client secret from the Intercom Developer Hub (your app → Basic information).
  2. Set DEVOTEL_INTERCOM_CLIENT_SECRET in the API service environment and restart.
  3. Trigger a test webhook from the Intercom webhook settings; expect 200.

​
Calendly

Calendly is the one receiver whose 503 carries WEBHOOK_NOT_PROVISIONED instead of WEBHOOK_DISABLED — the signing key is per-tenant and is minted by the connect flow, not read straight from an env var:
  1. Re-run the Calendly connect flow end to end: finish integrations/calendly/connect-complete for the organization so the webhook subscription and its per-tenant signing key are registered.
  2. Re-deliver one event from the Calendly webhook subscription page; expect 200.
  3. If the code persists after a clean connect-complete run, the subscription was registered under a different organization — check which organization id the callback query parameter carries and connect that one.

​
DIDWW address-verification callback

  1. Choose a high-entropy token and set DEVOTEL_DIDWW_CALLBACK_SECRET to it.
  2. The same token must be the path token embedded in the callback URL DIDWW posts to — a mismatch here is a 401, not this 503.
  3. Re-run the address-verification request from the DIDWW portal; expect 200.
Owner/operator action required for every receiver on this page: only an operator with access to the service environment (or to the integration’s connect flow) can clear these codes. A partner re-sending events does not help — every delivery 503s until the secret exists.

​
Counter observability

Each receiver-disabled arm increments a *_webhook.receiver_disabled counter tagged with the receiver route (for example hubspot_webhook.receiver_disabled and salesforce_webhook.receiver_disabled), and the arm logs at error level. A sustained counter increment means the secret is missing, not that signatures are failing — alert on it as a misconfigured-receiver page, separate from *_webhook.hmac_invalid signature-drift counters. Calendly arms calendly_webhook.receiver_disabled with the tenant and organization ids attached.

​
What not to do

  • Do not disable signature verification to make the 503 stop. A receiver without a secret is rejecting correctly; weakening verification accepts unverifiable events.
  • Do not ask the provider to retry harder. HubSpot / Salesforce / Intercom retries on 503 will keep failing — nothing recovers until the secret is set and the service restarted.
  • Do not confuse the 503 with a 401 signature failure. Recovery for 401 is secret alignment, never an env-var set. Decode the status code first.
  • Do not treat Calendly’s WEBHOOK_NOT_PROVISIONED as an env-var problem. Its signing key is per-tenant and minted by the connect flow; re-run connect-complete, not the deployment.

​
See also