Skip to main content

​
Emergency Stop Runbook: The Org-Wide Kill Switch

The emergency stop is an org-wide, tenant-owned kill switch that halts all outbound messaging and dialer traffic for your organization with one API call. It exists for the incident where the previous remediation was a database UPDATE by an engineer: a misconfigured campaign, a carrier complaint wave, a fraud event, or an offboarding cutoff. This page is the incident operator’s runbook: when the emergency stop is the right tool, how to activate and deactivate it, exactly what it blocks (and deliberately doesn’t), and the fail-safes that bound its blast radius. The summarized API surface also lives inside Send Gates; this page is the operational guide you bookmark in an incident doc. All endpoints below are rooted at https://api.orbit.devotel.io/api/v1/compliance.
The emergency stop is a tenant-owned control: only your organization’s owner or admin roles can activate or deactivate it, and it scopes only to your organization. Orbit operates the platform; you operate the switch. This page is not legal advice — whether outbound traffic is permissible in a given scenario depends on your jurisdiction, recipients, and content. Confirm with qualified counsel.

​
When the emergency stop is the right tool

Reach for the emergency stop when the cost of one more outbound send is higher than the cost of halting everything:
  • Active abuse or a compromised sender — API keys, sender numbers, or campaign content behaving outside your policy.
  • Carrier or regulator complaint wave — a spike of TCPA/DNC complaints, a carrier block notice, or a regulator inquiry mid-flight.
  • Fraud triage — pump-and-dump, phishing-content detection, or any event where you need traffic frozen while on-call investigates.
  • Offboarding / contract termination — a hard cutoff of outbound capability for a departured sub-account or a terminated engagement.
It is not the right tool for a single bad list (use DNC scrub or message suppression), a channel-specific pause (use channel rate overrides), or routine quiet-hours gating (see Send Gates). Those controls are scoped; the emergency stop is intentionally not.

​
Activate

POST /emergency-stop/activate flips the switch ON. Requires an owner or admin API key — the kill switch is a high-blast-radius operation and is not available to developer or viewer roles.
Why the reason exists. The reason (optional, up to 500 characters) is stored on the switch and written to the audit log with the actor’s user id and the activation timestamp. In a post-incident review this is how you rebuild the timeline: who stopped what, when, and why. Write a reason a future reviewer will understand — the audit record is meant to be read months later, not minutes.

​
Behavior while ON

While the switch is active, the downstream send gate reads the flag at the top of every outbound dispatch path and rejects with HTTP 403 ORG_COMPLIANCE_EMERGENCY_STOP before the dispatcher selects a provider. Blocked channels:
  • SMS and MMS
  • Voice (outbound call origination)
  • Dialer campaign activation
  • Other messaging channels on the dispatch path (WhatsApp, RCS, Viber, Telegram, fax)
Explicit carve-outs. Two classes of traffic are deliberately not gated:
  • Verify/OTP sends, so a contact can still receive a login code or a two-factor token while the switch is active.
  • Email, which runs on a separate delivery path with its own suppression list.
If your incident also requires freezing OTP or email, disable the relevant Verify profile or email sender in the settings surface — don’t rely on the emergency stop for those paths.
Rejection happens before wallet hold and provider dispatch, so no balance is debited for a blocked send. The block decision, the channel, and the message id are emitted to the audit/event stream so you can correlate the freeze with the volume of stopped traffic afterward.

​
Deactivate

POST /emergency-stop/deactivate lifts the halt. Also owner/admin only; also audit-logged with the actor and timestamps.
Confirm the state immediately after deactivating:
GET /emergency-stop returns the current state:
Deactivate clears activated_at, activated_by, and reason back to null; the activation record itself remains in the audit log.

​
Fail-safes

The control is bounded by design so a panic-button click can’t go wrong in the ways a button can:
  • Once-per-incident write semantics. Activate and deactivate are rate-limited to 5 requests / minute — enough for one decisive click plus a few rage-retries, too slow to thrash the flag.
  • Cache invalidation. The state is cached at the API layer for a maximum of 30 seconds (a per-send database round-trip would otherwise sit on the message hot path). An activation is enforced across the fleet within that window; an immediate cache invalidation applies on the pod that served the write. Plan for blocking within half a minute of the POST.
  • Fail-open lookup posture. If the state lookup itself fails (a database hiccup), the gate treats the switch as OFF and logs — a transient read failure cannot black-hole every outbound send, and a reactivation POST after the DB recovers restores enforcement.
  • Least-privilege RBAC. Owner/admin only on both write endpoints; developer and viewer roles receive 403 and cannot hold the rope.

​
Run it as a drill

Add the emergency stop to your launch checklist and your incident runbook: pick a low-traffic moment, have an owner/admin activate, verify a blocked send returns 403 with ORG_COMPLIANCE_EMERGENCY_STOP, then deactivate and confirm the GET reads active: false. The go-live checklist references this page as a launch-day drill — an operator who has never flipped the switch in peacetime will fumble it in an incident. See also:
  • Send Gates — the consolidated send-control surface (quiet hours, DNC/RND/RMD, preference center) plus the emergency-stop API summary.
  • Opt-out and suppression — the narrower, always-on controls for individual contacts.
  • Audit Log — reading the activation/deactivation records this control writes.