Webhook

SimplifyTrip uses webhooks to notify your application whenever events occur on your data. Each webhook includes an event type, endpoint, HTTP method, and JSON payload.

You can view and manage webhook events delivered to your endpoint in Webhook statistics.

General conventions

• Content-Type: application/json
• Authorization: use X-Simplify-Trip-Signature header for verification
• Retry: maximum 3 retries, 5 minutes apart
• Idempotency: use id with sentDate, createdAt to avoid duplicate handling, and use type to identify payload Webhook list

Setup

Provide an endpoint in your system to receive webhooks. Webhook notifications are sent via POST to the configured URL. Configure webhook URL in API key settings. You can set one endpoint per API key or share one endpoint across multiple keys. You can use tools such as ngrok during testing.

Event Handling

Correct webhook handling is critical to ensure your business logic behaves as expected.

Acknowledge events immediately

If your webhook endpoint performs complex logic or network calls, it may time out before SimplifyTrip receives a success response. Ideally, acknowledge event receipt first (2xx), then process business logic asynchronously.

Handle duplicate events

Webhook endpoints may receive the same event multiple times. Make your event handling idempotent by storing processed events and skipping duplicates. Each webhook includes a unique webhook-id to help implement idempotency. Learn more about idempotency.

Event ordering

SimplifyTrip does not guarantee delivery order of events. Your endpoint should not assume event ordering and should handle out-of-order events safely. You can fetch missing objects through API.

Retry

SimplifyTrip retries webhook delivery unless your endpoint returns 4xx. Since 4xx indicates an issue in your system, automatic retry is skipped. Fix your system issue, then manually resend webhook from Webhook statistics.

Maximum automatic retries: 3. Retry interval: 5 minutes.

Security

Securing your endpoint is important to protect customer information. SimplifyTrip provides several ways to verify incoming events safely.

• Receive events through HTTPS server

  If your webhook endpoint uses HTTPS, SimplifyTrip verifies secure transport before sending payloads. Your server must be correctly configured with a valid TLS certificate.

• Replay protection:

  Check id, sentDate, and createdAt; accept each event once within a 24-hour window.

• Verify events sent from SimplifyTrip

  SimplifyTrip signs webhook events sent to your endpoint. A signature is generated for each event and sent in request header X-Simplify-Trip-Signature. This allows you to verify events are from SimplifyTrip, not third parties. See Verify data with signature.

Webhook list

eSIM order payload

Event payload after your eSIM purchase order is completed. Includes signature and order object with purchased eSIM list.

Physical SIM order payload

Event payload when physical SIM order status changes. Includes signature and order status object.

Return request payload

Event payload when return request status changes. Includes signature and return-status object.