​

Continuous monitoring: SIM-swap and roaming subscriptions

​

Check vs subscription: when to enroll

• High-value accounts. Accounts whose takeover would be catastrophic (large wallets, payout rails, admin roles) deserve monitoring that reacts in seconds, not at the next poll.
• Step-up windows. After a password reset, a new-device login, or a suspicious risk:score verdict, enroll the number for the risk window instead of polling sim-swap:check every few minutes until the window closes.
• Home-network fleets. IoT devices and domestic-only customer bases where a device answering abroad is itself the alert. That is the roaming subscription’s native use case.

1. subscriptionExpireTime — the subscription auto-expires at the RFC-3339 timestamp you set. Fit it to your risk window.
2. subscriptionMaxEvents — the operator stops after delivering that many events (1 to 1000). Useful as a safety cap.
3. DELETE — you tear the subscription down explicitly. Omit both limits and this is the only way it ends.

​

Enroll a number

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/sim-swap/subscriptions" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: enroll-account-8412" \
  -d '{
    "phoneNumber": "+14155550100",
    "notificationUrl": "https://fraud.example.com/webhooks/network-apis/sim-swap",
    "notificationAuthToken": "bearer-token-you-generated",
    "subscriptionExpireTime": "2026-11-29T09:00:00Z"
  }'

{
  "data": {
    "id": "sub-7f3a9c21",
    "status": "ACTIVE",
    "startsAt": "2026-10-30T09:12:00Z",
    "expiresAt": "2026-11-29T09:00:00Z"
  },
  "request_id": "req_01J9ZK",
  "timestamp": "2026-10-30T09:12:01Z"
}

• Send an Idempotency-Key. If your enroll call retries on a network error, the key prevents a second live subscription for the same number.
• notificationUrl must be HTTPS. Plain-HTTP and internal addresses are rejected with a 422.
• The roaming variant is the same call with a different path. POST /device-roaming-status/subscriptions takes the identical body; the operator then delivers roaming-on / roaming-off events instead of swapped.

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/device-roaming-status/subscriptions" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+14155550100",
    "notificationUrl": "https://fraud.example.com/webhooks/network-apis/roaming",
    "notificationAuthToken": "bearer-token-you-generated"
  }'

​

Read state and tear down

curl "https://api.orbit.devotel.io/api/v1/numbers/network-apis/sim-swap/subscriptions/sub-7f3a9c21" \
  -H "X-API-Key: $ORBIT_API_KEY"

curl -X DELETE "https://api.orbit.devotel.io/api/v1/numbers/network-apis/sim-swap/subscriptions/sub-7f3a9c21" \
  -H "X-API-Key: $ORBIT_API_KEY"

​

Consume the CloudEvents

1. Authenticate the callback. On this sink the operator presents your notificationAuthToken as an Authorization: Bearer header on every delivery. Reject anything else with a 401. (Orbit-dispatched webhooks elsewhere in the platform authenticate differently, with the X-Orbit-Signature HMAC; the pattern below swaps only the authenticity check.)
2. Dedupe on the event id. Delivery is at-least-once; the same event can arrive more than once. Persist seen ids in your database, not in memory, so dedupe survives restarts.
3. Ack fast. Verify, dedupe, enqueue, return 200. The decision logic runs in a queue worker, never inline in the handler.

import express from "express";

const expectedAuth = `Bearer ${process.env.SIM_SWAP_SINK_TOKEN}`;

const app = express();

app.post("/webhooks/network-apis/sim-swap", express.raw({ type: "*/*" }), (req, res) => {
  // 1. Authenticate: the operator echoes your notificationAuthToken as a bearer.
  if ((req.headers.authorization ?? "") !== expectedAuth) {
    return res.status(401).json({ error: "Invalid bearer" });
  }
  const event = JSON.parse(req.body.toString());

  // 2. Dedupe on the CloudEvent id; persist seen ids in your database.
  if (seenRecently(event.id)) return res.status(200).json({ duplicate: true });
  remember(event.id);

  // 3. Enqueue and ack immediately; the worker below does the real work.
  queue.enqueue(event);
  return res.status(200).json({ ok: true });
});

async function onSimSwapEvent(event: { type: string; data?: { device?: { phoneNumber?: string } } }) {
  if (event.type !== "org.camaraproject.sim-swap-subscriptions.v0.swapped") return;
  const phoneNumber = event.data?.device?.phoneNumber;
  if (!phoneNumber) return;

  // Your policy, your thresholds: a swap on a monitored number is a
  // strong account-takeover signal.
  await sessions.revokeForNumber(phoneNumber, { reason: "sim_swap_detected" });
  await auth.requireStepUpOnNextLogin(phoneNumber, { factor: "existing_method" });
}

​

Roaming on and off: pair before you act

• Persist the latest event type and timestamp per number when the worker processes an event; do not act inline.
• A scheduled pass evaluates only numbers whose state has been unchanged for your quiet window (30 to 60 minutes is a workable default for a domestic-only customer base).
• A roaming-off that follows a roaming-on inside the quiet window resolves it: the device came home, and the pair is a log line, not an alert.
• A roaming-on that survives the quiet window is your corroborating signal for the fraud review queue, alongside SIM-swap and device-swap verdicts.

​

Coverage and fail-soft

curl "https://api.orbit.devotel.io/api/v1/numbers/network-apis/status" \
  -H "X-API-Key: $ORBIT_API_KEY"

​

Tenant controls

​

In the console

​

What’s next

• Network signals before you send — the one-shot checks these subscriptions complement.
• Production webhook consumer checklist — the full receiver pattern: retry ladder, dead-letter replay, and the 7-day dedupe window.
• Network APIs reference — every endpoint’s parameters, response schema, and error contract.