Webhooks integration guide

Don't call us. We'll call you.

Polling is asking "are we there yet?" every five seconds. Webhooks are the platform tapping you on the shoulder the moment something happens: a call ended, a booking was made, a message arrived, a payment cleared. Your server exposes an HTTPS endpoint; esimgomobile POSTs a signed JSON event to it in near real time; you react.

This guide covers webhooks as an engineering discipline — receiving, verifying, retrying, and going idempotent — plus the esimgomobile event catalog. The receiver patterns are universal and production-ready today; the esimgomobile-specific event names are marked clearly as launching.

The event catalog

Events follow a consistent envelope: a unique id, a type, a created_at timestamp, and a data object with the full resource. Design your handlers around the envelope, not individual fields — new event types should flow through the same pipeline without code changes.

# illustrative envelope — final field names publish at launch
{
  "id": "evt_9f2k41",
  "type": "call.completed",
  "created_at": "2026-09-20T19:02:11Z",
  "data": {
    "call_id": "call_abc",
    "duration_s": 127,
    "summary": "Booked: crown consult, Thu 10:30…",
    "transcript_url": "https://…"
  }
}

Planned types: call.completed (transcript, summary, recording URL), booking.created / booking.cancelled (slot, caller, policy outcome), message.received (inbound SMS), esim.activated (line went live), payment.succeeded (checkout completed). Subscribe per endpoint — each URL gets only the types it needs.

Verify every signature, trust nothing else

Your webhook endpoint is a public URL that triggers actions in your system — creating bookings, sending messages, updating records. Anyone who can POST to it can impersonate the platform. Signature verification is the entire security model: every event carries an HMAC signature computed with your endpoint's secret; you recompute it over the raw body and compare in constant time.

# Python (Flask) — verify before you do anything else
import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["ESIM_WEBHOOK_SECRET"].encode()

@app.post("/webhooks/esimgomobile")
def webhook():
    raw = request.get_data()
    sig = request.headers.get("X-Esim-Signature", "")
    # header name illustrative — final name publishes at launch
    expected = hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, sig):
        abort(401)
    event = request.get_json()
    handle(event)  # your logic
    return {"ok": True}, 200

Three rules: verify on the raw body bytes (re-serialized JSON won't match), use constant-time comparison (hmac.compare_digest, never ==), and keep one secret per endpoint so rotation doesn't take everything down. Reject mismatches with 4xx — never process first and verify later.

Retries, backoff, and the 200 contract

The delivery contract is simple: we POST the event; if your endpoint doesn't answer 200 within seconds, we retry at increasing intervals — minutes, then longer, then hours — before flagging the event as dead-lettered for your inspection. Design your endpoint for this contract:

Reply 200 fast, work later. Acknowledge receipt immediately and process asynchronously (queue, background job). A handler that does slow work inline — CRM calls, email sends — will time out, and every timeout is a duplicate delivery later.

Expect duplicates. "At least once" delivery means the same event can arrive twice: a retry after your 200 got lost on the wire, a timeout you actually survived. Duplicates aren't bugs; unhandled duplicates are. Which brings us to:

# Node.js (Express) — idempotent handler skeleton
const seen = new Set(); // use Redis / DB in production

app.post("/webhooks/esimgomobile", express.raw({ type: "application/json" }), (req, res) => {
  if (!verify(req)) return res.sendStatus(401);   // Chapter 3
  const event = JSON.parse(req.body.toString());
  if (seen.has(event.id)) return res.sendStatus(200); // duplicate — skip
  seen.add(event.id);
  queue.add(() => handle(event));                 // async work
  res.sendStatus(200);
});

Test webhooks on your laptop

Webhook development needs your localhost reachable from the internet. Use a secure tunnel (your team's standard tooling), register the tunnel URL as a test endpoint, and trigger real events — place a test call, make a test booking — watching payloads land in your logs. Log the full raw body and headers first; parse second. When the handler is boring — verify, dedupe, queue, 200 — it's ready for production.

In production: HTTPS only, one endpoint per concern (don't route six event types through one giant switch if they have different owners), monitor delivery (alert on dead-letters, track handler latency), and version your endpoints (/webhooks/esimgomobile/v1) so future shape changes don't break you.

Before you ask.