​

Debug inbound carrier webhooks

​

Carrier webhook versus canonical outbound event

​

Inspect an inbound webhook record

• Signature badge — valid, invalid, or missing, against the provider’s signing scheme. A 401 on a forged POST still leaves an invalid row for forensics.
• Raw body — the request bytes, truncated to 256 KiB per row, with phone numbers and emails masked at insert time. ?reveal=true is never possible: the PII is reduced before the record is written.
• Parsed event drawer — the decoded JSON the handler parsed, likewise PII-masked. Header values are filtered to an allowlist (content type, request id, and the provider’s signature headers such as telnyx-signature-ed25519, x-meta-signature, x-hub-signature-256).
• API backing — GET /api/v1/developer/inbound-webhooks for the list, GET /api/v1/developer/inbound-webhooks/:id for the full raw body (raw_body_b64), headers, and parsed event. Filters: channel, provider, signature_status, from, to. Rows live 30 days, then are removed.

​

Map a raw provider status with the Inbound Event Catalog

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

• Telnyx UNDLV / SMPP DELIVRD family — message.sending_failed, sending_failed, delivery_failed, rejected, undelivered fold onto message.failed (a failure kind, failed status). Telnyx message.sent, queued, sending fold onto message.sent.
• SMPP codes through the Devotel softswitch — DELIVRD fold onto message.delivered; UNDLV, REJECTD, EXPIRED, and submitted_no_receipt fold onto message.failed.
• Meta (WhatsApp / Messenger / Instagram) read receipt — the read status folds onto message.read (a delivery kind). A delivered from the same channel folds onto message.delivered.
• Meta opt-outs — user_opt_out, marketing_opt_out, a STOP keyword, or opt_out fold onto contact.opted_out (a canonical opt-out event, opted_out status).
• Generic inbound (MO) — mo, inbound, received, message fold onto message.received (a received kind). The “a message arrived” branch is carrier-agnostic by construction.

​

Validate your receiver with the SDK

import { Orbit } from '@devotel-orbit/node';
import { normalizeInboundEvent } from '@devotel/shared/webhooks/inbound-normalization';

app.post('/webhooks/orbit', (req, res) => {
  const event = Orbit.webhooks.constructEvent(
    req.rawBody,
    req.headers['x-orbit-signature'] as string,
    process.env.ORBIT_WEBHOOK_SECRET!,
  );

  switch (event.type) {
    case 'message.delivered':
      // carrier DLR received
      break;
    case 'message.read':
      // WhatsApp read receipt
      break;
    case 'message.failed':
      // terminal failure — the raw carrier string is on data.provider_status
      break;
    case 'contact.opted_out':
      // opt-out signal (STOP keyword or Meta preference)
      break;
    case 'message.received':
      // inbound MO message
      break;
    default:
      break;
  }

  // Validate a carrier status you saw in the parsed event drawer:
  const normalized = normalizeInboundEvent({
    raw_status: 'UNDLV',
    provider: 'devotel_softswitch',
  });
  // → { event: 'message.failed', status: 'failed', kind: 'failure', ... }

  res.status(200).json({ received: true });
});

​

Troubleshoot carrier-specific POSTs

• Signature badge is invalid or missing — the provider signature header is either absent or rejected. The allowlist keeps the provider’s own signature header (for example telnyx-signature-ed25519, x-meta-signature) on the record, so you can compare the exact header and timestamp the carrier sent. A 401 was already returned for it, but the record still exists so the forgery trail stays auditable.
• Parsed event drawer is empty — the body could not decode as JSON (a proxy or a provider-side form-encoding issued it), so only the raw, PII-masked bytes survived. Decode the request’s content-type, and check the provider’s contract for the exact payload shape.
• Error row persists — the record carries an error field when the handler captured a message (for example a malformed Meta verification payload). The error text is PII-masked the same way the body is.
• Per-carrier quirks — SMPP bodies decoded from percent-encoded or foreign encodings can carry literal NUL bytes (a UTF-16BE receipt that ends in \x00); those bytes are stripped when the record is stored, so a record always persists even on a mangled payload. Meta sends statuses[] arrays and user_preferences blocks — the parsed drawer shows the whole decoded structure, so look for those nested entries, not a flat status field.
• Row missing entirely — the inbound-webhook log is best-effort by design: the handler’s 2xx never blocks on it. If the platform-log table is absent on a fresh deploy, records stop silently; on a live tenant a missing row means a platform-side fault, so treat it as an anomaly and check with support rather than assume the callback never arrived.

​

Next steps

• Webhooks endpoints — the fold-table API reference (the catalog lives under /api/v1/webhooks/inbound-events).
• Message status map — the canonical status vocabulary every receiver branch uses.
• First webhook quickstart — wire a receiver that consumes the canonical events this guide normalizes.
• Verify webhook signatures with the SDK, per language — sign-in details for the receiver pairing above.
• Event sources (Kafka inbound) — publish your own domain events into Orbit; the inbound filter vocabulary is the same in both directions.