> ## Documentation Index
> Fetch the complete documentation index at: https://docs.esimmu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Issued eSIMs and refund decisions, delivered to your URL

We POST JSON to the webhook URL registered for your account. Three events, told
apart by the `X-Esimmu-Event` header:

| `X-Esimmu-Event` | When |
| - | - |
| `esim.issued` | An eSIM you ordered has been issued. One delivery per unit |
| `esim.refunded` | A [refund request](https://docs.esimmu.com/endpoints/request-refund.md) was approved |
| `esim.refund_declined` | A refund request was declined |

## Delivery and retries

* **Acknowledge with any `2xx` within 10 seconds.** Anything else, including a
  timeout, is retried.
* **Retries back off over about four and a half hours**, eleven attempts in
  all. After that the delivery stops and we follow it up by hand.
* **The same delivery can arrive more than once.** Deduplicate on `topup_id`
  together with the event.
* **Acknowledge first, process after.** Verify the signature, store the
  payload, answer `200`, then do the slow work. A handler that does the work
  before answering is the usual cause of timeouts and duplicate deliveries.

## `esim.issued`

```json theme={null}
{
  "external_order_id": "ORD-1001",
  "topup_id": "202611161200000000000001",
  "option_id": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
  "iccid": "89852342022247881682",
  "smdp": "rsp1.example.com",
  "activate_code": "D1D88A9B4C7C4AA8BC75978D8D14F2E3",
  "download_link": "LPA:1$rsp1.example.com$D1D88A9B4C7C4AA8BC75978D8D14F2E3",
  "qrcode_img_url": "https://api.esimmu.com/qr/p_0123456789abcdef0123456789abcdef.png",
  "expired_date": "2027-05-15"
}
```

| Field | |
| - | - |
| `external_order_id` | Your order, as you sent it |
| `topup_id` | The unit, as returned by [Create an order](https://docs.esimmu.com/endpoints/create-order.md) |
| `option_id` | The product |
| `iccid` | The eSIM's ICCID |
| `smdp`, `activate_code` | SM-DP+ address and activation code, for manual installation |
| `download_link` | The LPA activation string. Durable: keep it |
| `qrcode_img_url` | A PNG of the QR code. Opaque, see below |
| `expired_date` | Last day to install and activate (`YYYY-MM-DD`) |

> [!NOTE]
>
> **Treat `qrcode_img_url` as opaque.** Do not parse it or depend on its host.
> The QR encodes exactly the `download_link` string and nothing else, so you can
> render your own from it if you prefer. Use error correction M, a quiet zone
> of 4 modules and at least 8 px per module, or cameras may not lock on.

Payloads can gain fields over time. Ignore the ones you do not recognise,
including any not listed here.

## Refund events

```json theme={null}
{
  "event": "esim.refunded",
  "topup_id": "202611161200000000000001",
  "iccid": "89852342022247881682",
  "refunded_at": "2026-11-21T05:30:00Z"
}
```

```json theme={null}
{
  "event": "esim.refund_declined",
  "topup_id": "202611161200000000000001",
  "iccid": "89852342022247881682",
  "declined_at": "2026-11-21T05:30:00Z",
  "decline_reason": "Data was used"
}
```

A declined request can be sent again; see [Asking
again](https://docs.esimmu.com/endpoints/request-refund.md#asking-again).

## Verifying the signature

Every delivery carries two headers alongside `X-Esimmu-Event`:

| Header | Value |
| - | - |
| `X-Esimmu-Webhook-Timestamp` | Unix seconds at the time we signed the delivery |
| `X-Esimmu-Webhook-Signature` | Comma-separated list of hex HMAC-SHA256 signatures. Accept the delivery if **any** entry matches |

The signed string is the timestamp, a full stop, and the raw request body:

```
{timestamp}.{raw_body}
```

Compute HMAC-SHA256 over that string with your **webhook signing secret**,
hex-encode it, and compare against each entry in the header.

> [!WARNING]
>
> The webhook signing secret is not your secret key. The secret key signs the
> requests you send us; the webhook signing secret verifies the webhooks we send
> you. See [Two secrets, two
> conventions](https://docs.esimmu.com/authentication/overview.md#two-secrets-two-conventions).

Four details decide whether your implementation works:

1. **Use the raw body, not a re-serialised object.** Parsing the JSON and
   serialising it again reorders keys and changes whitespace, so the signature
   will never match. Capture the raw body before any body-parsing middleware
   runs.
2. **Use the secret verbatim.** It is a plain string, not Base64. Do not decode
   it.
3. **Compare in constant time.** A plain `==` leaks the expected signature one
   character at a time through its timing.
4. **Reject stale timestamps.** The timestamp is inside the signed string, so a
   captured delivery cannot be replayed under a new one. Rejecting anything
   older than five minutes closes the remaining window.

```javascript Node.js theme={null}
const crypto = require("crypto");

// express.raw() keeps the body as a Buffer; express.json() would not.
app.post("/webhooks/esimmu", express.raw({ type: "application/json" }), (req, res) => {
  const rawBody = req.body.toString("utf8");
  const timestamp = req.get("X-Esimmu-Webhook-Timestamp");
  const header = req.get("X-Esimmu-Webhook-Signature") || "";

  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return res.sendStatus(401);
  }

  const expected = crypto
    .createHmac("sha256", process.env.ESIMMU_WEBHOOK_SECRET)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const matched = header.split(",").some((candidate) => {
    const received = Buffer.from(candidate.trim(), "utf8");
    const computed = Buffer.from(expected, "utf8");

    return received.length === computed.length && crypto.timingSafeEqual(received, computed);
  });

  if (!matched) return res.sendStatus(401);

  // Acknowledge first, process asynchronously. Deliveries are retried, so
  // enqueue() should ignore an event it has already handled.
  res.sendStatus(200);
  enqueue(req.get("X-Esimmu-Event"), JSON.parse(rawBody));
});
```

```python Python theme={null}
import hashlib
import hmac
import os
import time

from flask import Flask, request

app = Flask(__name__)


@app.post("/webhooks/esimmu")
def esimmu_webhook():
    raw_body = request.get_data(as_text=True)
    timestamp = request.headers.get("X-Esimmu-Webhook-Timestamp", "")
    header = request.headers.get("X-Esimmu-Webhook-Signature", "")

    if abs(time.time() - int(timestamp)) > 300:
        return "", 401

    expected = hmac.new(
        os.environ["ESIMMU_WEBHOOK_SECRET"].encode(),
        f"{timestamp}.{raw_body}".encode(),
        hashlib.sha256,
    ).hexdigest()

    if not any(hmac.compare_digest(expected, candidate.strip()) for candidate in header.split(",")):
        return "", 401

    # Deliveries are retried, so enqueue() should ignore an event it has
    # already handled.
    enqueue(request.headers.get("X-Esimmu-Event"), request.get_json())

    return "", 200
```

```ruby Ruby theme={null}
require "openssl"
require "rack/utils"

post "/webhooks/esimmu" do
  raw_body = request.body.read
  timestamp = request.env["HTTP_X_ESIMMU_WEBHOOK_TIMESTAMP"].to_s
  header = request.env["HTTP_X_ESIMMU_WEBHOOK_SIGNATURE"].to_s

  halt 401 if (Time.now.to_i - timestamp.to_i).abs > 300

  expected = OpenSSL::HMAC.hexdigest("SHA256", ENV.fetch("ESIMMU_WEBHOOK_SECRET"), "#{timestamp}.#{raw_body}")

  matched = header.split(",").any? { |candidate| Rack::Utils.secure_compare(expected, candidate.strip) }

  halt 401 unless matched

  # Deliveries are retried, so enqueue() should ignore an event it has
  # already handled.
  enqueue(request.env["HTTP_X_ESIMMU_EVENT"], JSON.parse(raw_body))

  status 200
end
```

### Test vector

```
webhook signing secret : whsec_test_signing_secret     (used verbatim, not decoded)
timestamp              : 1754400000
raw body               : {"external_order_id":"ORD-1001","topup_id":"202611161200000000000001"}

signed string : 1754400000.{"external_order_id":"ORD-1001","topup_id":"202611161200000000000001"}
signature     : 5866a6ef7e1547eb2a19f96ac29fa5cf1e80e50cf9985cb2c6c1faf6979454fa
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.