​

Wire delivery-report webhooks per channel, end to end

​

1. Event vocabulary per channel

​

The changed semantics you must code against

• Meta DM (Messenger, Instagram): no DLR exists. Meta’s Send API never emits delivery receipts, so a DM send can only produce message.sent followed by either nothing or a safety-net message.failed reading submitted_no_receipt after a 5-minute window. Treat message.sent as fully accepted on these channels and do not alert on the missing message.delivered — it will never come. See DLR outcomes monitoring for the designed-benign classification.
• Viber and WhatsApp: a 24-hour DLR window. A send that receives no receipt inside 24 hours ages to undelivered and fires message.failed — a late genuine receipt still corrects the row and re-fires message.delivered (or message.read). Your consumer must accept a correcting event after a terminal one.
• SMS on SMPP-backed routes: a 30-minute window. A healthy carrier returns receipts well inside 30 minutes. A send with no receipt inside that window ages to undelivered and fires message.failed; a late receipt corrects it. A sustained no-receipt rate on this lane is a carrier problem, not a platform problem.
• Email semantics are mailbox-acceptance. message.delivered means the receiving server accepted the message — it is not an open or a click. Pair it with the engagement events (email.opened, email.clicked) if you need recipient interaction.
• Voice has no delivery concept. call.answered is the voice equivalent of delivered; call.failed covers busy, no-answer, and carrier failure. Subscribe to the full call lifecycle instead of a single event.

​

2. Subscribe

​

In the dashboard

​

Over the API

curl -X POST https://api.orbit.devotel.io/api/v1/webhooks/endpoints \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/orbit",
    "events": [
      "message.sent",
      "message.delivered",
      "message.read",
      "message.failed",
      "call.initiated",
      "call.answered",
      "call.completed",
      "call.failed"
    ]
  }'

​

3. Verify the signature

​

Node.js (standard library)

import crypto from "node:crypto";

export function verifyOrbitSignature(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(
    (header ?? "").split(",").map((kv) => kv.split("=")),
  );
  const timestamp = Number(parts.t);
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`, "utf8")
    .digest("hex");
  const received = Buffer.from(parts.v1 ?? "", "hex");
  const expectedBuf = Buffer.from(expected, "hex");
  if (received.length !== expectedBuf.length) return false;
  const fresh = Math.abs(Date.now() / 1000 - timestamp) <= toleranceSec;
  return fresh && crypto.timingSafeEqual(received, expectedBuf);
}

​

Python (standard library)

import hashlib
import hmac
import time

def verify_orbit_signature(raw_body: bytes, header: str, secret: str,
                           tolerance_sec: int = 300) -> bool:
    """Verify an Orbit webhook signature header.

    raw_body: exact bytes received — verify before any JSON parser runs.
    header: value of X-Orbit-Signature (fall back to X-Devotel-Signature).
    """
    parts = dict(item.split("=", 1) for item in header.split(","))
    timestamp = int(parts.get("t", "0"))
    if abs(time.time() - timestamp) > tolerance_sec:
        return False
    signed = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

​

4. Sandbox rehearsal — tester first, then a real subscription

curl -X POST https://api.orbit.devotel.io/api/v1/messages \
  -H "X-API-Key: dv_test_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "to": "+15005550003", "from": "+15550100", "body": "DLR rehearsal" }'

​

5. Debug a delivery

1. meta.request_id on the API response. Every send response carries it. Open Developer → Request Logs, find the request by id, and confirm Orbit accepted the send — a 422 or 502 at the request layer means no DLR events will ever fire.
2. data.message_id (and data.to, the recipient id) on the event envelope. Open the Delivery Log filtered by the message id. The row’s terminal status is the ground truth; the webhook event you expected is downstream of the same transition the row shows. Check Developer → Webhooks → your endpoint → Deliveries for the dispatch record — a failing endpoint shows its failed attempts and the retry timeline there.

​

Compliance

​

Related

• Webhook events catalog — the canonical list of every event you can subscribe to
• Build a durable webhook consumer — queue, dedupe, and ack-fast hardening for the receiver this page wires
• Verify webhook signatures — one-call SDK verifiers per language
• Webhook Tester — the unsigned ad-hoc sender used in Step A
• DLR outcomes monitoring — the WARN classification behind the no-receipt terminal events
• Sandbox magic numbers playbook — the full trailing-digit scenario table
• Delivery lifecycle — what each of the six canonical states means