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

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

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

A declined request can be sent again; see Asking again.

Verifying the signature

Every delivery carries two headers alongside X-Esimmu-Event: The signed string is the timestamp, a full stop, and the raw request body:
Compute HMAC-SHA256 over that string with your webhook signing secret, hex-encode it, and compare against each entry in the header.
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.
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.

Test vector

Last modified on November 16, 2026