• 228 destinations
  • No KYC, ever
  • Bitcoin, Monero, USDT and 4 more

DevelopersAdvanced8 min readUpdated 18 October 2026

Running delivery webhooks in production

Verify signatures on the raw body, answer in seconds, deduplicate, order by status, replay and rotate secrets: a webhook handler built for real traffic.

Part 3 of 4 in the path Building on the API

Verify first

Every event carries two headers, X-Meteor-Timestamp and X-Meteor-Signature; the signature header reads t=…,v1=…, and the hex digest to compare is the part after v1=. The signature is an HMAC-SHA256 over the timestamp, a dot and the raw request body, keyed with your endpoint secret. Recompute it, compare in constant time, and reject timestamps older than five minutes so a captured request cannot be replayed later. Do it before parsing: a body that has been parsed and re-serialised will not match, even when it looks identical. In Flask the raw body is request.get_data(), in Django request.body; in Express, mount a raw body parser on the webhook route.

Python
import hashlib, hmac, os, time

# Comma-separated, so a rotation can hold two secrets for a while.
SECRETS = [s.encode() for s in os.environ["WEBHOOK_SECRETS"].split(",")]

def verify(raw_body, timestamp, signature):
    # X-Meteor-Timestamp holds Unix seconds; X-Meteor-Signature holds "t=...,v1=<hex digest>".
    try:
        ts = int(timestamp)
    except (TypeError, ValueError):
        return False
    if abs(time.time() - ts) > 300:        # five minutes
        return False
    given = (signature or "").split("v1=")[-1].encode()
    signed = timestamp.encode() + b"." + raw_body
    for secret in SECRETS:
        expected = hmac.new(secret, signed, hashlib.sha256).hexdigest()
        if hmac.compare_digest(expected.encode(), given):
            return True
    return False

The same check in Node:

Node.js
const crypto = require("crypto");

function verify(rawBody, timestamp, signature, secrets) {
  const ts = Number(timestamp);
  if (Number.isNaN(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false;
  const given = Buffer.from(String(signature || "").split("v1=").pop());
  return secrets.some((secret) => {
    const expected = Buffer.from(crypto.createHmac("sha256", secret)
      .update(timestamp + ".").update(rawBody).digest("hex"));
    return expected.length === given.length && crypto.timingSafeEqual(expected, given);
  });
}

Answer 401 when verification fails and log the reason, never the secret. The webhook documentation is the reference for header formats, and the HMAC signature entry explains the principle.

Acknowledge fast

You have 5 seconds to answer with any 2xx. Do not do the work in the request: verify, write the event to a queue or a table, return 200. A handler that updates three systems inline will time out on the day one of them is slow, and each timeout becomes a retry that may arrive while the first attempt is still running.

The arithmetic makes the case. Say a campaign of 100,000 messages produces up to two events per message, sent then delivered or failed: 200,000 requests. Spread over an hour, that is about 56 a second on average (200,000 ÷ 3,600), and peaks are higher. A handler that spends 300 ms on inline work needs about 17 requests in flight just to keep pace with the average (56 × 0.3); one that stores a row and returns in 20 ms needs about one.

Python
@app.post("/hooks/sms")
def sms_hook():
    raw = request.get_data()                  # raw bytes, before any parsing
    if not verify(raw, request.headers.get("X-Meteor-Timestamp", ""),
                  request.headers.get("X-Meteor-Signature", "")):
        return "", 401
    inbox_insert(raw)                         # durable write; duplicates ignored
    return "", 200                            # everything else happens in a worker

Answer 2xx only once the event is stored. If the database is down, return a 5xx and let the retry schedule bring the event back, rather than acknowledging something you have lost.

Deduplicate

Retries happen, and every attempt carries the same event id. Store the ids you have processed under a unique index and treat a duplicate as success. This is the whole of idempotent handling, and it is one table:

SQL
CREATE TABLE webhook_inbox (
  event_id     text PRIMARY KEY,
  payload      jsonb NOT NULL,
  received_at  timestamptz NOT NULL DEFAULT now(),
  processed_at timestamptz
);

INSERT INTO webhook_inbox (event_id, payload)
VALUES (:event_id, :payload)
ON CONFLICT (event_id) DO NOTHING;

A worker takes the rows where processed_at is empty, applies them and sets it, in one transaction. Replays from the panel keep the original event id too, so a bulk replay is safe even when some of those events had already arrived. The same idea protects your outbound calls; see idempotency key.

Order by status, not by arrival

Delivery order is not guaranteed, and replays arrive days later by design. If you store the last event received, a late sent will undo a delivered. Give each status a rank and only ever move forward:

StatusRankCan be replaced by
queued0sent, delivered, failed
sent1delivered, failed
delivered, failed2Nothing: both are final
SQL
UPDATE messages
   SET status = :status, status_rank = :rank
 WHERE id = :message_id AND status_rank < :rank;

Do not order by the X-Meteor-Timestamp header: a replay carries a new timestamp and signature with the original event id, so the header says when the event was signed, not when the message changed state. On destinations that return carrier acknowledgement only, sent is the final positive state and no delivered will follow; each country page says which kind of receipt to expect.

Route events by type

Five event types describe outbound messages: message.sent, message.delivered, message.failed, message.expired and message.rejected; campaign and balance events complete the list of ten, and each endpoint subscribes only to the ones it uses. If you rent a number with inbound, replies arrive as events too. Dispatch on the type in the worker, not in the request handler, and answer 2xx to types you do not handle yet, so a new type is stored and ignored rather than retried six times.

Two fields on the original message make routing simple. reference, up to 128 characters of your own, is echoed in webhooks, so an event finds its order, appointment or verification without a lookup table. webhook_url overrides the endpoint for one message, HTTPS only, which lets code traffic report straight to the authentication service while campaign traffic goes to analytics. A message.failed event carries a plain reason and the raw carrier code; why SMS fail says what each reason calls for.

Retries, outages and replays

Each event gets 6 attempts over 24 hours: immediately, then +1 min, +5 min, +30 min, +2 h and +12 h. After the last one it is marked undelivered. Any answer other than a 2xx within 5 seconds is a failed attempt, 401 and 404 included, so a route that moved in a deploy, or a secret changed in one place and not the other, looks exactly like an outage.

  • A deploy or a blip costs nothing: later attempts land after you are back.
  • An outage of a few hours delays events rather than losing them, as long as the later attempts fall after you recover.
  • A day or more, or a wrong secret answering 401 to everything, exhausts all six attempts, and the events wait in the panel as undelivered.

Fix the endpoint first, confirm with a single replay, then replay the rest in bulk. Replays keep the original event id with a new timestamp and signature, so they pass the five-minute check, deduplication absorbs any event you already had, and the status ranking handles the order. The undelivered list holds events for 30 days; there is more on replays from the panel.

Monitor both sides

On your side, alert on:

  • your 5xx rate, and your 401 rate: a jump in 401 just after a deploy is usually a secret or body-parsing problem, not an attack;
  • handler latency above two seconds, well inside the 5-second limit;
  • the depth of the inbox and the age of its oldest unprocessed row, which catch a stalled worker that endpoint metrics never see.

In the panel, each endpoint shows its success rate, last failure and average response time, and the undelivered list gives the last status code or error for each event. Read them together: a falling success rate with a fast average response usually means the endpoint is answering quickly with the wrong status code.

Rotate the secret

Rotate when someone who knew the secret leaves, when it may have been exposed, and on a schedule. After a rotation from the panel, the old and the new secret are both valid for 24 hours, so a verifier that accepts a list keeps working through the change:

  1. Rotate in the panel and copy the new secret.
  2. Add it to the verifier's list next to the old one, and deploy.
  3. Log which secret matched; once events verify with the new one, remove the old secret, well within the 24 hours.

Keep the secret in a secret store or an environment variable, never in the repository or in logs.

Test before launch

Messages sent with an sk_test_ key are validated and priced like live ones; nothing is sent or billed, and webhooks still fire, signed like live ones. That makes the whole path testable for free; see test keys. Before the first real campaign, check that:

  1. a genuine event is stored and answered within a second;
  2. the same body with one byte changed gets 401;
  3. a timestamp ten minutes old gets 401;
  4. the same event delivered twice produces one row;
  5. delivered followed by a late sent leaves the status at delivered;
  6. with the database stopped, the handler answers 5xx quickly instead of hanging.
Put it into practice.An email address opens the account. Rates are public, payment is crypto, and the test key is free.
Start sending

Something unclear or out of date? Tell us on the support page; corrections are folded back into the guide and the update date changes.