# Webhooks (/docs/webhooks)

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 [#events]

| Event | Sent when |
|---|---|
| [`order.fulfillment.updated`](/docs/api-reference/webhooks/order-fulfillment-updated) | An 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.refunded`](/docs/api-reference/webhooks/order-item-refunded) | A refund of an item progresses or completes, including the automatic refund of a rejected item |
| [`order-item.manual-amendment.status`](/docs/api-reference/webhooks/order-item-manual-amendment-status) | A hotel manual amendment changes status, including when it needs your action |
| [`esim.profileStatus.updated`](/docs/api-reference/webhooks/esim-profile-status-updated) | An eSIM's profile status changes, for example when it is installed |
| [`esim.usage.updated`](/docs/api-reference/webhooks/esim-usage-updated) | An eSIM's data usage crosses a threshold |
| [`partner.balance.low`](/docs/api-reference/webhooks/partner-balance-low) | A wallet balance falls into a lower configured threshold band |

The [API reference](/docs/api-reference/webhooks/order-fulfillment-updated) documents the body of each event.

## The request [#the-request]

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

| Header | Value |
|---|---|
| `X-OpenRoam-Webhook-Id` | The id of the webhook that delivers the event |
| `X-OpenRoam-Timestamp` | The signing time, in Unix seconds (UTC) |
| `X-OpenRoam-Event-Id` | The event id. Deduplicate by it |
| `X-OpenRoam-Signature` | The HMAC-SHA256 signature, lowercase hex |

```json
{
  "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 [#verify-the-signature]

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

```text
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:

```ts
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](/docs/sdks) include a helper that verifies the signature for you.

## Delivery and retries [#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 [#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 [#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`.