Build your first webhook receiver

This walkthrough takes you from zero to your first verified Orbit delivery. By the end you have a receiver that verifies the signature, deduplicates retries, and routes each event type to a handler — plus the retry semantics to reason about it in production. The same pieces exist deeper in the reference docs; this page puts them in build order. Security is the canonical signature reference with verifiers in seven languages, Event payloads documents the envelope and headers, and Inspecting deliveries covers replay tooling.

Step 1 — Register an endpoint and copy the secret

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",
    "events": ["message.delivered", "message.failed"]
  }'

The response includes the cleartext signing secret (whsec_...). This is the only time it is shown — copy it immediately and store it as an environment variable, never in code. Subscribe to a narrow event list while you develop; broad * subscriptions generate far more traffic than a new integration needs.

Step 2 — Serve a POST endpoint with a raw body

Verification signs the raw request body, so your receiver must read the body before any JSON middleware parses it. Keep the raw bytes around. Node (Express — register express.raw() on this route before any global express.json()):

import express from 'express';
import crypto from 'node:crypto';

const app = express();

const seen = new Set(); // replace with durable storage (Redis / a DB table) in production

function parseSignatureHeader(header) {
  const parts = header.split(',').map((p) => p.trim());
  let t = null;
  const v1s = [];
  for (const part of parts) {
    const eq = part.indexOf('=');
    if (eq < 0) continue;
    const key = part.slice(0, eq);
    const value = part.slice(eq + 1);
    if (key === 't') t = value;
    else if (key === 'v1') v1s.push(value);
  }
  return { t, v1s };
}

function verifySignature(rawBody, header, secret) {
  if (!header) return false;
  const { t, v1s } = parseSignatureHeader(header);
  if (!t || v1s.length === 0) return false;

  // Replay protection: reject signatures older than 5 minutes.
  const ageSec = Math.floor(Date.now() / 1000) - Number(t);
  if (!Number.isFinite(ageSec) || ageSec < 0 || ageSec > 5 * 60) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`, 'utf-8')
    .digest('hex');
  const expectedBuf = Buffer.from(expected, 'hex');

  return v1s.some((candidate) => {
    const candidateBuf = Buffer.from(candidate, 'hex');
    return (
      candidateBuf.length === expectedBuf.length &&
      crypto.timingSafeEqual(candidateBuf, expectedBuf)
    );
  });
}

app.post('/webhooks/orbit', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf-8');

  // Step 3 — verify the signature
  const header = req.headers['x-orbit-signature'] ?? req.headers['x-devotel-signature'];
  if (!verifySignature(rawBody, header, process.env.ORBIT_WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(rawBody);

  // Step 4 — dedup by event id
  if (seen.has(event.id)) {
    return res.status(200).json({ received: true, duplicate: true });
  }
  seen.add(event.id);

  // Step 5 — route by event type
  switch (event.type) {
    case 'message.delivered':
      // mark the message delivered in your system
      break;
    case 'message.failed':
      // alert, queue a retry, or notify the sender
      break;
    default:
      // acknowledge unknown types so new events don't jam retries
      break;
  }

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

app.listen(3000);

Python (Flask):

import hmac
import hashlib
import os
import time
from flask import Flask, jsonify, request

app = Flask(__name__)
seen = set()  # replace with durable storage (Redis / a DB table) in production


def parse_signature_header(header: str):
    t = None
    v1s = []
    for part in header.split(","):
        part = part.strip()
        if "=" not in part:
            continue
        key, _, value = part.partition("=")
        if key == "t":
            t = value
        elif key == "v1":
            v1s.append(value)
    return t, v1s


def verify_signature(raw_body: bytes, header: str, secret: str) -> bool:
    if not header:
        return False
    t, v1s = parse_signature_header(header)
    if not t or not v1s:
        return False

    # Replay protection: reject signatures older than 5 minutes.
    age = int(time.time()) - int(t)
    if age < 0 or age > 5 * 60:
        return False

    signed = f"{t}.".encode("utf-8") + raw_body
    expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()

    return any(hmac.compare_digest(candidate, expected) for candidate in v1s)


@app.route("/webhooks/orbit", methods=["POST"])
def handle_webhook():
    # Step 3 — verify the signature
    header = request.headers.get("X-Orbit-Signature") or request.headers.get(
        "X-Devotel-Signature", ""
    )
    if not verify_signature(request.data, header, os.environ["ORBIT_WEBHOOK_SECRET"]):
        return jsonify({"error": "Invalid signature"}), 401

    event = request.get_json()

    # Step 4 — dedup by event id
    if event["id"] in seen:
        return jsonify({"received": True, "duplicate": True}), 200
    seen.add(event["id"])

    # Step 5 — route by event type
    if event["type"] == "message.delivered":
        pass  # mark the message delivered in your system
    elif event["type"] == "message.failed":
        pass  # alert, queue a retry, or notify the sender

    return jsonify({"received": True}), 200

The Python SDK ships the same verifier as orbit_sdk.verify_webhook(payload, signature, secret) — one call that raises OrbitWebhookSignatureError on failure and returns the decoded event dict. The Node verifier above is the same logic with no dependency. Verifiers in Go, Ruby, PHP, Java, and C# are on Webhook security.

Step 3 — Verify the signature (shown above)

Both receivers read the canonical X-Orbit-Signature header and fall back to the legacy X-Devotel-Signature, parse the t=<unix>,v1=<hex> format, reject timestamps older than 5 minutes, and compare HMAC_SHA256(secret, "<t>.<raw_body>") with a timing-safe comparison. During a secret-rotation grace window the legacy header carries two v1 candidates — the “accept if any matches” logic above handles that without changes. Return 401 on failure and stop — never process an unverified payload.

Step 4 — Deduplicate by event id

Delivery is at-least-once: a timeout or retry can deliver the same event twice. The envelope id (evt_...) is stable across every retry of one event, and the Idempotency-Key header mirrors it. Persist every id you process and return 200 immediately for a duplicate — a fast duplicate ack is better than re-firing billable work downstream. Keep ids for at least 7 days, which covers the full retry window plus the dead-letter replay window.

Step 5 — Map event types to handlers

Route on event.type and acknowledge types you do not handle. New event types appear over time; a receiver that returns 4xx on an unknown type burns its retry budget on events it never wanted. The full catalog of type values is on Webhook events.

Retry semantics — the concrete timings

If your endpoint returns a non-2xx response or does not answer within 30 seconds, Orbit retries the delivery on an exponential backoff schedule: one initial delivery plus 9 retries (10 attempts total). The backoff starts at 30 seconds and doubles each retry:

Attempt	1	2	3	4	5	6	7	8	9	10
Delay before it	—	30 s	60 s	120 s	240 s	480 s	960 s	1,920 s	3,840 s	7,680 s

Up to 20% extra jitter is applied on top, so a burst of failures against one endpoint does not retry in lockstep. The whole schedule spans roughly 4.3 hours — after the 10th attempt fails, the event moves to the dead-letter queue. Response codes mean specific things:

Any 2xx within 30 seconds — success, no retry.
Timeout or 5xx — always retries.
Retryable 4xx (400, 422, …) — retries until the schedule is exhausted.
401, 403, 404, or 410 Gone — proven-dead: skips retries, moves to the dead-letter queue, and immediately disables the endpoint (the org admin is notified). 410 Gone is also how you permanently skip retries for a lone event type you have deprecated.

50 consecutive failures on one endpoint also auto-disables it. Re-enable from the dashboard once your receiver is healthy; deliveries to a disabled endpoint go straight to the dead-letter queue.

Dead-letter queue and replay

After retries exhaust, events sit in the dead-letter queue for 7 days, replayable from the dashboard under Developer → Webhooks → Dead-letter queue or over the API:

# List dead-lettered deliveries
curl https://api.orbit.devotel.io/api/v1/webhooks/dlq \
  -H "X-API-Key: dv_live_sk_..."

# Requeue one delivery
curl -X POST https://api.orbit.devotel.io/api/v1/webhooks/dlq/dlv_abc123/requeue \
  -H "X-API-Key: dv_live_sk_..."

For a single failed delivery from the event timeline, use Replay on the delivery row, or POST /api/v1/webhooks/{endpoint_id}/deliveries/{delivery_id}/replay — failed-only, same endpoint, within 7 days. The dashboard flow and bulk paths are on Inspecting deliveries.

Test the loop

Run the receiver locally and expose it with a tunnel (ngrok http 3000).
Register the tunnel URL, subscribe to one event type, and copy the cleartext secret.
Trigger a real event (send a test SMS) and watch the signature verify, the handler run, and a 200 go back.
Flip the receiver off and re-trigger — watch the retry schedule in Developer → Webhooks → Events, then bring the receiver back and replay the failure.

If signatures fail to verify, work through Troubleshooting: Signature Verification Failures — the common case is a JSON middleware consuming the raw body before verification.

Getting Started

Channels

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Changelog

Build your first webhook receiver

Build your first webhook receiver

Step 1 — Register an endpoint and copy the secret

Step 2 — Serve a POST endpoint with a raw body

Step 3 — Verify the signature (shown above)

Step 4 — Deduplicate by event id

Step 5 — Map event types to handlers

Retry semantics — the concrete timings

Dead-letter queue and replay

Test the loop

See also

​Build your first webhook receiver

​Step 1 — Register an endpoint and copy the secret

​Step 2 — Serve a POST endpoint with a raw body

​Step 3 — Verify the signature (shown above)

​Step 4 — Deduplicate by event id

​Step 5 — Map event types to handlers

​Retry semantics — the concrete timings

​Dead-letter queue and replay

​Test the loop

​See also

Build your first webhook receiver

Step 1 — Register an endpoint and copy the secret

Step 2 — Serve a POST endpoint with a raw body

Step 3 — Verify the signature (shown above)

Step 4 — Deduplicate by event id

Step 5 — Map event types to handlers

Retry semantics — the concrete timings

Dead-letter queue and replay

Test the loop

See also