​

Inbound event catalog

​

Open the catalog

​

The catalog endpoint

curl -X GET "https://api.orbit.devotel.io/api/v1/webhooks/inbound-events" \
  -H "X-API-Key: dv_live_sk_..."

​

Read an entry

​

A folding entry you can read end-to-end

{
  "id": "evt_f01d4mp1e",
  "type": "message.failed",
  "created_at": "2026-08-26T12:00:00Z",
  "data": {
    "message_id": "msg_abc123",
    "channel": "sms",
    "status": "failed",
    "provider_status": "UNDLV",
    "normalized": {
      "event": "message.failed",
      "status": "failed",
      "kind": "failure",
      "provider": "devotel_softswitch",
      "raw_status": "undlv"
    }
  }
}

​

Which carriers report which vocabulary

​

When to use normalized.inbound vs subscribing per event

• One share subscription — set the endpoint’s event list to ["normalized.inbound"] and it receives the whole family (message.received, message.delivered, message.failed, message.read, contact.opted_out) without enumerating events. Choose this when your handler keys off data.normalized.kind (delivery / failure / opt_out / received) and you never want to miss a status family.
• Per-event subscriptions — list the specific events (["message.delivered", "message.failed"]). Choose this when separate teams or pipelines own separate outcomes — for example a deliverability dashboard subscribed to message.failed only — or when a success pipeline should not have to filter out opt-outs.

curl -X POST "https://api.orbit.devotel.io/api/v1/webhooks" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/orbit-inbound",
    "events": ["normalized.inbound"]
  }'

​

Receiver validation with the SDK

import { normalizeInboundEvent } from "@devotel/shared/webhooks/inbound-normalization";

const result = normalizeInboundEvent({
  provider: "devotel_softswitch",
  raw_status: "UNDLV",
});
// => {
//   event: "message.failed",
//   status: "failed",
//   kind: "failure",
//   provider: "devotel_softswitch",
//   raw_status: "undlv",
//   mapping: { ... }
// }

​

Reading provider_status in a handler

function handleDelivery(envelope) {
  const { status, provider_status, message_id } = envelope.data;

  switch (status) {
    // Canonical, closed set — one branch covers every carrier.
    case "failed":
      alertDeliverability(message_id, provider_status);
      break;
    case "delivered":
      markDelivered(message_id);
      break;
  }

  // provider_status is the carrier's own string, echoed verbatim.
  // Reach for it when the canonical layer is not enough — for example
  // distinguishing an SMPP "expired" from "rejectd" inside one failure.
  if (status === "failed" && provider_status === "expired") {
    scheduleRetry(message_id);
  }
}

​

Put it to work

1. Search the raw status (for example UNDLV) in the catalog.
2. Read off the canonical event it resolves to (for example message.failed) and the canonical data.status (for example failed).
3. Check that your handler’s switch covers that canonical event — SMPP UNDLV-style codes, Telnyx failure strings, and DIDWW statuses can all fold into the same event.

​

Common misreads to avoid

• “The carrier said delivered, but Orbit reports failed.” Normalization collapses carrier nuance into a closed set. An SMPP UNDLV receipt and a DIDWW undelivered both land as message.failed with data.status of failed — the original string survives in data.provider_status, so a handler that greps the raw string and ignores the canonical field misbranches. Conversely, Telnyx queued and sending fold to message.sent (kind delivery), not delivered: only message.delivered, delivered, or delivery_success mean delivered.
• Treating read as a delivery outcome. Meta read is its own canonical event (message.read); subscribe to it explicitly or it looks like a missing message.delivered branch.
• Expecting one canonical event per provider. The event list on an endpoint says which canonical events to receive; the provider that produced them is data on the envelope (data.normalized.provider), not part of the event name. SMPP UNDLV, Telnyx rejected, and DIDWW undelivered all arrive as message.failed.
• Assuming unknown statuses are dropped. A raw status the catalog does not cover returns undefined from normalizeInboundEvent; the platform logs it and keeps the carrier-verbatim data.provider_status on the delivery — it is never silently swallowed.

​

When you want the schema instead

​

See also

• Webhook Events catalog — every event type you can subscribe to
• Webhook Event Payloads — the full envelope and header anatomy
• Normalized inbound event envelope — the data.normalized block and the normalized.inbound share subscription
• Webhook Security — signature verification