X-Esimmu-Event header:
Delivery and retries
- Acknowledge with any
2xxwithin 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_idtogether 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.Refund events
Verifying the signature
Every delivery carries two headers alongsideX-Esimmu-Event:
The signed string is the timestamp, a full stop, and the raw request body:
- 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.
- Use the secret verbatim. It is a plain string, not Base64. Do not decode it.
- Compare in constant time. A plain
==leaks the expected signature one character at a time through its timing. - 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.