Skip to main content

​
Troubleshooting: inbound SMS not reaching your webhooks

Inbound SMS (mobile-originated messages, or carrier delivery receipts) should land in your Inbox and fire your message webhooks the moment the carrier hands the traffic to Orbit. If one of your numbers receives texts but nothing is recorded — no Inbox row, no webhook payload — work the checks below in order.

​
Check the routing first

Orbit resolves every inbound message to a tenant by looking the destination number up in the platform’s number index, then falling back to a bounded scan of tenant records. A message can only be dropped in this path when:
  1. The destination number is not in an active, pending_compliance, or suspended state — e.g. released after a teardown, or nothing owned the number at the time of arrival.
  2. The number’s routing index entry is missing or points at a tenant that has since been offboarded (deleted).
Check the Numbers page: if the number reads released or was never purchased, routing correctly did not resolve. If the number reads one of the three routed states but inbound still never lands, the index entry is the suspect.

​
The self-healing index

Orbit runs an hourly background reconciliation that scans every live tenant’s SMS-capable numbers and re-creates any routing index entries that drifted — for example after a purchase-time write failed silently, or after an out-of-band administrative edit bypassed the normal write path. Inbound routing correctness is not subscription-gated: a tenant whose subscription has cancelled keeps its SMS-capable numbers reconcilable. Because reconciliation runs hourly, a one-time drift usually self-clears within one hour. If inbound was missing and spontaneously returns after the next hourly window, that is the expected self-heal path — no support action needed.

​
Work by observation pattern

  • One specific number never gets inbound, while other tenants’ numbers do. If the number is in a routed state and the gap persists beyond a couple of hours, the hourly reconciliation should already have repaired it — open a support ticket; this class is the customer-facing symptom that should never survive the hourly sweep.
  • Most inbound stops at once across many numbers. That is not a per-number index problem. Check whether inbound webhooks are returning non-2xx answers from your receiver (Orbit acks always return 200 to the carrier, but your handler may be silently misauthoring) or whether a dashboard-per-DID route override was recently set to disabled.
  • Only DLRs are missing but MO arrives fine. DLRs follow the same resolution path as MO messages; a missing-receipt DLR is always a carrier late-arrival problem first — see the delivery-receipt troubleshooting page.

​
When to escalate

Open a support ticket when one of these holds:
  • A number in a routed state (active, pending_compliance, or suspended) has not recorded inbound for more than 2 hours and you have already ruled out a disabled per-DID override.
  • You see the “optional” route configuration panel set the sms_route_type for that DID to disabled — clear the override first, then confirm inbound resolves again.
  • All inbound stops across many unrelated numbers (a control-plane symptom, not an index one).
To let support trace the gap without a back-and-forth, capture:
  • The affected E.164 number (+12345678900) from the Numbers page.
  • Your tenant ID (dashboard → Settings → Organization; or GET /api/v1/me as organizationId).
  • A timestamp of one inbound attempt that did not record.

​
See also