eSIM Webhooks for Resellers: Best Practices for Orders, Activations and Expiry

Short answer: eSIM webhooks tell your system the moment something happens to an order or an eSIM, so you can email the QR code, flag a failure or remind a customer to top up without polling. With the eSIM Signal partner programme you receive signed webhooks for order.completed, order.failed, order.refunded, esim.activated and esim.expired; the best practice is to verify the HMAC-SHA256 signature, answer quickly, process the work in the background, and make every handler safe to run twice.

The webhook events and what to do with them

• order.completed: the eSIM is ready. Send the customer their install link and QR code, and mark the order paid and delivered in your system.
• order.failed: the order did not go through. Tell your support team, show the customer a clear message and offer an alternative plan.
• order.refunded: a refund has been made to your balance. Refund or credit your own customer, and update your accounting.
• esim.activated: the customer has started using the plan. A good moment for a "you're connected" email with tips, and to stop sending install reminders.
• esim.expired: the plan has ended. Send a thank-you, a review request or an offer for the next trip.

If you are new to the API, start with the eSIM reseller API integration guide, then come back here.

1. Verify every signature

Each webhook carries an HMAC-SHA256 signature in the X-ESIMSIGNAL-Signature header. Before you trust a payload:

1. Compute the HMAC-SHA256 of the raw request body with your webhook secret.
2. Compare it with the header using a constant-time comparison.
3. Reject the request if they do not match.

Two common mistakes:

• Hashing the parsed JSON instead of the raw body. Re-serialising can change spacing or key order and break the match. Capture the raw bytes first.
• Logging the secret or committing it to a repository. Keep it in environment variables or a secrets manager.

2. Answer fast, work later

Your endpoint should acknowledge a webhook quickly with a 2xx status and do the heavy lifting afterwards:

• Store the event (or push it to a queue)
• Return 200 straight away
• Process it in a background job: emails, CRM updates, accounting

Slow handlers that send emails or call other services before replying are the most common cause of timeouts in any webhook system.

3. Make handlers idempotent

In any webhook system you should expect that the same event can arrive more than once, and design for it:

• Record which events you have processed, keyed on the order or eSIM and the event type.
• Skip work you have already done, such as a delivery email that was already sent.
• Use your own customer_ref on orders so every event can be matched to your customer without guesswork.

On the ordering side, send an Idempotency-Key with each order request so a retry after a network error does not create a second eSIM.

4. Do not depend on event order

Network delays mean events may not arrive in the order they happened. Build handlers that read the current state rather than assuming a sequence:

• If an esim.activated event arrives for an order you have not marked completed yet, look up the order through the API before acting.
• Treat each event as "something changed; check the latest state" rather than as a full history.

5. Use webhooks to cut support tickets

Most reseller support questions are predictable, and webhooks let you answer them before they are asked:

• No esim.activated a day after the trip starts? Send an install reminder with a link to your install guide.
• order.failed? Email the customer immediately with a fix, rather than letting them discover it at the airport.
• esim.activated on a small plan? Mention top-ups: the API supports GET /esims/{iccid}/topups and POST /esims/{iccid}/topup.

Our customer support playbook for eSIM resellers covers the human side.

Tip: keep a simple admin page that lists the last webhook events per order. When a customer writes in, your support team can see at a glance whether the eSIM was delivered, activated or refunded.

6. Test safely

• Use read-only test keys to explore the catalogue and responses without placing orders.
• Build a local signature test that signs a sample body with your secret and checks your verification code.
• Log every request your endpoint receives (without secrets) while you develop, so you can replay problems.

7. Secure the rest of the integration

• Scope your API keys: catalogue, orders, esims and refunds scopes let each system use only what it needs.
• Use the IP allow-list for keys that place orders.
• Rotate keys when people leave the team, and give team members their own Business Panel logins with admin or user roles.

The docs include a request and response example for every endpoint, and they can be downloaded as a PDF for your team.

Apply for a partner account

Frequently asked questions

Which webhook events does eSIM Signal send?

order.completed, order.failed, order.refunded, esim.activated and esim.expired.

How do I verify an eSIM Signal webhook?

Compute an HMAC-SHA256 of the raw request body with your webhook secret and compare it with the X-ESIMSIGNAL-Signature header using a constant-time comparison.

Why should webhook handlers be idempotent?

In any webhook system an event can arrive more than once. Idempotent handlers make sure a repeat does not send a second email or double a refund.

Can I match webhooks to my own customers?

Yes. Send your own reference in customer_ref when you place the order, and use it to match every event.

Can I test the API without placing real orders?

Yes. Read-only test keys let you explore the catalogue and responses without ordering.