​

Migration playbook hub

The vendor-specific guides each map one source platform’s concepts onto Orbit. This hub covers the shape every migration shares — account, sandbox, numbers, data, templates, webhooks, parallel-run, cutover — so a migration from a platform with no dedicated guide still has an exact playbook, and a migration from one of the covered platforms knows where its guide sits in the sequence. Read your vendor’s guide for the concept mapping (what the source calls a messaging service, an app, a flow). Read this hub for the order of operations, because that order does not change with the source.

​

1. Hub map — pick the guide for your source

Everything in Section 2 applies to each of these. When your source is not in the table — a regional aggregator, an in-house gateway, a hosted SMSC — apply Section 2 directly: the send endpoint changes per vendor, the migration shape does not.

​

2. Vendor-agnostic skeleton — the eight universal steps

Every vendor-specific guide runs the same eight steps; the vendor guides replace step-content where the source platform forces it (for example, Sinch batch sends, Vonage JWTs). Use this checklist for a source with no dedicated guide, and as the audit spine for a covered one. Section outline vs vendor column: on a covered vendor, each row above maps to one or more sections in that vendor’s guide — the row is the constant, the guide is the variable. On an uncovered vendor, the rows are your whole vendor column.

​

3. Number-port sequencing — leave correctly

Which move the number makes depends on what your legacy provider is to the number, not on which send API you used. Decide per number before you queue anything. Sequence numbers ahead of everything downstream: ports take days to weeks per country, so the port clock starts before templates are re-authored — not after. A send-side migration that waits on zero ports is the fast lane; plan for it only after the decision table says no number physically moves.

​

4. Runbook for cutover — the canonical seven steps

Cutover is the one step that touches live traffic, so it is a checklist, not a migration phase. Freeze, redirect, swap, flip, verify, hold, close. Each step carries its verification command — do not proceed past a step whose check failed.

1. Freeze sends on the legacy platform. Stop new dispatches at the traffic manager or code path that selects the provider; drain in-flight batches. Verify: the legacy console’s outgoing queue reads zero new entries for a full drain window, while your Orbit-side traffic keeps flowing on the parallel-run split.
2. Redirect webhook receivers. Point your event consumer at Orbit signatures and event names (or point Orbit’s webhooks at your existing receiver — the receiver wins, the signature check changes). Verify: curl a replayed message.delivered against your receiver and confirm the X-Orbit-Signature verification passes:
   curl -X POST https://yourapp.example.com/webhooks/orbit \
     -H "Content-Type: application/json" \
     -H "X-Orbit-Signature: <computed-hmac>" \
     -d '{"type":"message.delivered","data":{...}}'
   # Expect 2xx from your own verified handler — a signature error here means
   # the secret, not the receiver, is wrong.
   
3. Swap API keys at the sender. Move X-API-Key values from the legacy credential to the Orbit key in your secret store; revoke the legacy key only after Step 6. Verify: a probe send through the production path lands on Orbit:
   curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
     -H "X-API-Key: dv_live_sk_..." \
     -H "Content-Type: application/json" \
     -d '{"to":"+14155552671","body":"cutover probe"}'
   # Expect data.status: queued — and a delivered webhook within the parallel-run's observed window.
   
4. Flip sender identity. Route production traffic onto the Orbit-registered sender — the ported number, the approved 10DLC campaign, the active sender ID. Verify: the probe’s from on the recipient handset matches the identity the destination market expects (short-code, alphanumeric ID, or ported long code), not a fallback.
5. Watch the first-hour parity window. Compare Orbit’s delivery rate on the previously-split traffic class against the legacy baseline you measured in parallel-run. Verify: parity holds within your tolerance on the insights dashboards; a sustained dip reopens Step 2’s signature and Step 4’s identity findings before it reopens routing.
6. Hold the fallback warm. Keep the legacy credential and routing hook alive, unused, for an agreed window — typically one full billing cycle or two peak weeks. Verify: a controlled canary through the legacy path still reaches its destination, so a rollback is a config flip, not a rebuild.
7. Decommission the legacy account. Close it only after the hold window passes and the legacy credential carries zero remaining sends. Verify: the legacy account shows no active numbers, no queued campaigns, and no webhook commitments your receiver still depends on — then close, and record the close date in your own ops log.

​

5. Operations after cutover

Cutover ends the traffic move; operations is what keeps the migration honest afterward.

• Migration job history. Platform-migration jobs (wizard-run imports of contacts and configuration) live past onboarding on Settings → Migrations — every job with its status, its failure reason, and its rollback state. A finished job that imported wrong rows can still be rolled back after cutover; the operations surface and the API for it are in Monitor, cancel, and roll back platform migrations.
• Audit ledger. Every migration-relevant change — the import run, the rollback, the key rotation, the port submission — lands in the tenant audit log. When a post-cutover discrepancy appears (a contact that lost its opt-out, a webhook consumer that stopped receiving), the audit ledger is the timeline that says which step introduced it; see the audit log guide for reading and exporting it.
• Suppression and consent state. Opt-outs collected during the parallel-run on the legacy platform must exist in Orbit before decommission. Check the exported suppression list against Orbit’s per-channel suppression; a missed row is a compliance defect, not a cosmetic one.