Skip to main content

​
Inbound Country Gate

The inbound country gate is a per-tenant policy for the inbound webhook path. It answers one question on every inbound SMS, voice, and WhatsApp-over-phone message: which country did this originate from, and do you want it to land in your inbox? You use it to shut down artificially-inflated-traffic (AIT) and smishing sources, or to enforce a strict data-flow posture such as EU-only inbound origins. This page is the concept guide. For the request/response schema, see API Reference → Settings Compliance. Nothing on this page makes Orbit a compliance regulator for your traffic — this is a tenant-owned control: you own the policy, you set it, and Orbit enforces exactly what you set.

​
What the gate answers

Inbound fraud rarely announces itself at the platform layer. A tenant in a fraud-targeted vertical (OTPs, wallets, fan-out APIs) can see a surge of inbound SMS from one or two countries pumping billable traffic, or a smishing ring injecting phishing messages into your inbox. The inbound gate lets you drop those origins before the message lands, or record them for review without dropping. What it is not: a compliance-gating decision, an OFAC/embargo rail, or a platform mandate. Orbit does not decide which countries you accept inbound traffic from. The gate is a tenant-owned fraud and data-flow control, not a jurisdiction filter.

​
The three modes

Use flag first when you are not sure which origins are legitimate — it tells you what the policy would have blocked without breaking any real traffic. Move to block once the flag view confirms the pattern.

​
Resolution model

The gate resolves the sender’s origin through the same phone-country resolver the outbound allowlist uses — libphonenumber-js with a longest-prefix fallback. Resolution is phone-channel only:
  • An email address resolves to no country (allowed through).
  • A synthetic chat identifier (bsuid:, PSID, line:, fb:, ig:) resolves to no country.
  • The literal "unknown" sender resolves to no country.
Non-phone senders are deliberately skipped so the gate never mis-rejects a chat-only sender. When the resolver cannot confidently resolve a country at all, the gate fails open — the message passes through. The gate only ever acts on a confidently-resolved origin, in either direction: an allowlist violation needs a resolved country that is not on the list; a blocklist violation needs a resolved country that is on it.

​
Policy shape

Three fields under settings.fraud configure the gate: Codes are upper-cased and deduped before they are persisted, so the shape the API returns is always the shape the evaluator sees. An allowlist, when present, wins over the blocklist — an allowlist is the stricter, fully-specified policy, so the blocklist is ignored while the allowlist is active. Both lists empty (or mode off) means the gate is inert. If you set only lists and no explicit mode, the default posture is block — parity with the outbound allowlist’s default-deny.

​
Configuration

Reads are open to any member who can read settings (S_READ); writes are restricted to the organization owner, because this control decides which inbound origins ever reach your inbox.
Read back the current posture:
The PUT endpoint validates the payload with exact ISO-2 shape (two letters, letters only) and rejects with 422 VALIDATION_ERROR on anything else.

​
How this composes with the outbound allowlist

The outbound country allowlist is the counterpart control — it rejects outbound destinations to unlisted countries on SMS, messaging, and voice. The two are independent and deliberately composable:
  • Outbound allowlist constrains where your sends can go.
  • Inbound country gate constrains which origins can land.
A tenant that wants an EU-only data-flow posture normally wants both: you don’t dial out to the wrong country, and you don’t accept inbound traffic from it either. A fraud-targeted tenant may want only one (outbound open, inbound blocked), or the inverse. Set what your traffic needs; neither control implies the other.

​
When to use it — and cautions

Use it when:
  • You are in a fraud-targeted vertical (OTP, wallet, API fan-out) and see recurring AIT or smishing from one or two origin countries.
  • You have a strict data-flow posture (EU-only, US-only) that should hold for inbound messages too, not just outbound sends.
  • You want flag-only visibility into inbound origin countries before you commit to blocking.
Cautions:
  • Default from off. The gate does nothing until you configure it. Setting lists without a mode defaults to block — which can drop legitimate traffic the moment it lands. Start with flag, confirm the pattern, then move to block.
  • Phone-channel only. Email and chat-only senders are always allowed through; do not expect the gate to gate them.
  • Fail-open on unresolvable origin. If the resolver can’t resolve a country, the message passes. A mis-E.164 sender that should be blocked is your responsibility to catch elsewhere in your fraud stack.
  • Compliance Posture Overview — where this row sits in the toggle map (fail-open posture alongside the outbound allowlist).
  • Fraud Shield — the triage surface for fraud alerts the platform raises; the inbound gate’s flagged traffic can feed the same review workflow.
  • Channel Rate Overrides — the outbound throughput rail; a different control, often set alongside the country rails.
  • API Reference → Compliance — full request/response schemas for these endpoints.