Skip to Content
OpenRoam Docs

Webhooks

Receive signed events when orders are delivered, refunded or amended, and when eSIMs change.

OpenRoam sends events to an HTTPS endpoint you register in the partner dashboard. Each environment has its own webhooks and signing secrets. When you create a webhook you choose its events; for order.fulfillment.updated you can also choose the order origins it receives (api, dashboard, or both).

Events

EventSent when
order.fulfillment.updatedAn order's delivery changes: items delivered or rejected, a later result, a confirmed cancellation of a delivered item, or the order reaching partiallyRefunded or refunded
order-item.refundedA refund of an item progresses or completes, including the automatic refund of a rejected item
order-item.manual-amendment.statusA hotel manual amendment changes status, including when it needs your action
esim.profileStatus.updatedAn eSIM's profile status changes, for example when it is installed
esim.usage.updatedAn eSIM's data usage crosses a threshold
partner.balance.lowA wallet balance falls into a lower configured threshold band

The API reference documents the body of each event.

The request

Each delivery is a POST with a JSON body and four headers:

HeaderValue
X-OpenRoam-Webhook-IdThe id of the webhook that delivers the event
X-OpenRoam-TimestampThe signing time, in Unix seconds (UTC)
X-OpenRoam-Event-IdThe event id. Deduplicate by it
X-OpenRoam-SignatureThe HMAC-SHA256 signature, lowercase hex
{
  "eventId": "9e9ac90f-0df2-4533-a3c6-7a0dc4a6c08f",
  "eventType": "order.fulfillment.updated",
  "timestamp": 1770000000,
  "data": {
    "orderId": "3db22f3e-8a20-4e64-9f89-5ab49ef39f4d",
    "origin": { "channel": "api" },
    "status": "fulfillmentFailed",
    "fulfillmentVersion": 2,
    "items": [
      {
        "id": "11111111-2222-3333-4444-555555555555",
        "productType": "airtime",
        "fulfillment": {
          "status": "rejected",
          "result": null,
          "failure": { "code": 11001, "name": "FULFILLMENT_REJECTED", "message": "The order item could not be fulfilled." }
        }
      }
    ]
  }
}

The order.fulfillment.updated item carries id, productType and fulfillment only. fulfillment.result has the same shape as in the order read. Read the order for everything else.

Verify the signature

OpenRoam signs the string timestamp.eventId.rawBody with your webhook's signing secret (not your API key):

signature = hex(HMAC_SHA256(signingSecret, `${timestamp}.${eventId}.${rawBody}`))

rawBody is the request body exactly as received, before any JSON parsing. A minimal Node.js receiver with Express:

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

const app = express();
const secret = process.env.OPENROAM_WEBHOOK_SECRET!;
const maxDriftSeconds = 300;

// Keep the raw bytes: the signature covers the body exactly as sent.
app.post('/webhooks/openroam', express.raw({ type: '*/*' }), (req, res) => {
  const timestamp = req.header('X-OpenRoam-Timestamp') ?? '';
  const eventId = req.header('X-OpenRoam-Event-Id') ?? '';
  const signature = (req.header('X-OpenRoam-Signature') ?? '').toLowerCase();

  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(age) || age > maxDriftSeconds) return res.sendStatus(401);

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${eventId}.${req.body.toString('utf8')}`)
    .digest('hex');
  // A signature is 64 hex characters; anything else is refused before the comparison, which needs equal lengths.
  const valid =
    /^[0-9a-f]{64}$/.test(signature) &&
    crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(signature, 'hex'));
  if (!valid) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString('utf8'));
  // Store the event, deduplicated by event.eventId, then process it in the background.
  res.sendStatus(200);
});

The SDKs include a helper that verifies the signature for you.

Delivery and retries

  • Delivery is at least once. You may receive an event more than once: deduplicate by X-OpenRoam-Event-Id.
  • Events can arrive out of order, and several can arrive at the same time. For order.fulfillment.updated, never replace a higher fulfillmentVersion with a lower one.
  • Answer 2xx once you have stored the event. Process it afterwards: each attempt times out after about 60 seconds.
  • Any other answer, a timeout or a network error is retried, except 410 Gone, which stops delivery of that event for good.
  • Retries wait 30s, 2m, 5m, 15m, 30m, 1h, 2h, 4h, 8h and 12h: up to 11 attempts over about 28 hours. Each retry has a fresh timestamp and signature.
  • A 401 for a bad signature is retried too, so an event still arrives once you fix your clock or secret.
  • OpenRoam support can deliver an event again on request, with the same event id and body.

The partner dashboard shows the delivery history of each webhook, with every attempt and its result.

Test deliveries

From the dashboard you can send a test event to a webhook. It arrives like a real event, with the usual headers and signature, and a top-level "isTest": true in the body. Verify it as usual, acknowledge it with 2xx, and keep it out of your business processing.

Events and the order read

An event is a snapshot of the moment it was sent. The order read always returns the current state, so read the order when you need the full picture. Refunds and amendments have their own events and do not change fulfillmentVersion, with two exceptions: the confirmed cancellation of a delivered item, and the completed refund that moves the order to partiallyRefunded or refunded. Both also send order.fulfillment.updated.

On this page