Webhooks

Webhooks push domain events (esim.provisioned, bundle.usage_threshold, esim.suspended, …) to your server as they happen, so you don’t have to poll.

1. Register an endpoint

curl -X POST https://api.sandbox.interglobe.io/v1/webhook_endpoints \
  -H "Authorization: Bearer $IG_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your.app/webhooks/interglobe", "enabled_event_types": ["*"] }'

The response includes a signing secret (whsec_…) — it’s returned once. Store it; you’ll use it to verify every delivery. Pass specific event types instead of ["*"] to subscribe selectively.

2. Verify the signature

Each delivery carries an InterGlobe-Signature: t=<unixSeconds>,v1=<hex> header, where hex = HMAC-SHA256(secret, "<t>.<rawBody>"). Verify over the raw request body (not a re-serialized object) and reject if it doesn’t match or the timestamp is stale.

The TypeScript SDK does this for you:

import { constructWebhookEvent } from "@interglobe/sdk";

// In your HTTP handler — pass the RAW body string and the signature header:
const event = constructWebhookEvent(rawBody, req.headers["interglobe-signature"], process.env.WHSEC!);
// throws if the signature is invalid or the timestamp is outside the tolerance window

switch (event.type) {
  case "esim.provisioned":
    // event.data.iccid …
    break;
}

Respond 2xx quickly (do heavy work asynchronously).

3. Retries, replay, auto-disable

• Retries: a non-2xx or timeout is retried with exponential backoff.
• Auto-disable: an endpoint that keeps failing is automatically disabled — check GET /v1/webhook_endpoints/{id} (disabled_reason) and re-enable once you’ve fixed it.
• Replay: re-deliver a past event with POST /v1/events/{id}/replay, and browse the log at GET /v1/events.
• Test delivery: POST /v1/events/test publishes a synthetic event through the real pipeline so you can exercise your handler on demand.

Thin payloads

Deliveries carry a small, version-stable payload — correlation ids plus minimal data, not full resource state:

{ "id": "evt_…", "type": "esim.provisioned", "object": "event", "created": 1784160000, "data": { "iccid": "…" } }

Fetch current state from the API (at your pinned version) if you need more than the event carries.