Webhooks

Configure an endpoint

Provide your HTTPS endpoint to Akariq during onboarding. Its hostname must be explicitly approved, and Akariq configures the webhook for your account. There is no partner-facing webhook-registration endpoint today.

Store the supplied signing secret securely. It is distinct from your API key. Polling remains available if you do not use webhooks.

Events and payloads

Supported event types are order.fulfilled, order.failed and balance.low. Low-balance notifications are generated when an order reservation crosses the configured threshold; also check your balance directly.

An order notification has this shape:

{
  "id": "order:example-order-id:fulfilled",
  "type": "order.fulfilled",
  "createdAt": "2026-09-21 10:00:00",
  "data": {
    "orderId": "example-order-id",
    "status": "fulfilled"
  }
}

Notifications contain IDs and status, not QR codes or activation secrets. Read the current order state through the API before delivering an eSIM.

Verify before processing

Requests include X-Akariq-Event-ID and this signature header:

X-Akariq-Signature: t=TIMESTAMP,v1=HEX_SIGNATURE

1. Capture the exact raw UTF-8 request body before JSON parsing.
2. Parse t and v1 from the header. Reject missing or malformed values.
3. Reject a timestamp more than five minutes from your server’s clock.
4. Compute HMAC-SHA256 with your webhook secret over TIMESTAMP + "." + RAW_BODY.
5. Compare the hexadecimal digest with v1 using a constant-time comparison.
6. Persist the event ID and the work to perform, then return a 2xx response.

Never calculate the signature over re-serialized JSON: whitespace and field ordering affect the digest. A known event ID should receive a successful acknowledgement without repeating its business action.

Retries and recovery

Delivery attempts have a ten-second timeout. Redirects are not followed. Failed deliveries are retried with exponential backoff, up to eight attempts, with the delay capped at one hour.

Events may arrive more than once or out of order. Store processed event IDs durably and make delivery idempotent. If notifications stop, poll order status and contact Akariq to inspect or retry exhausted events.

Changing your webhook rotates its signing secret. Coordinate the receiver update with Akariq before replacing the endpoint or secret.