Webhooks - Ionic Docs

A webhook is an HTTP request Ionic sends to a URL you control when something happens in your account — a payment succeeds, a refund settles, a subscription changes. Instead of polling the API, you register an endpoint once and Ionic delivers each event as it occurs. Use webhooks for work that happens after payment: fulfill an order, send a receipt, provision access, or update your records. A redirect only tells you that the buyer returned to your site. Confirm payment from a verified webhook or an API response before fulfilling the order.

How it works

Tell Ionic which URL to deliver to with POST /v1/webhook_endpoints. You receive a signing secret once, at creation time.

Receive events

Ionic sends each event as a POST with a JSON envelope in the body. Respond 2xx quickly to acknowledge receipt.

Verify and act

Verify the signature on every request, then act on the event — idempotently, because the same event can arrive more than once.

Delivery semantics

Read these guarantees carefully — they determine how you must write your handler.

Guarantee	What it means for you
At-least-once	An event may be delivered more than once. Deduplicate on the envelope `id` (the `evt_` value).
Ordering is not guaranteed	Events can arrive out of order. Don’t infer state from arrival order — read the resource snapshot in `data.object`, or fetch the current resource from the API.
Retried with backoff	A non-`2xx` response (or a timeout) is retried on a backoff schedule. A handler that errors will see the event again.
Acknowledge fast	Do the minimum to record the event, return `2xx`, and process asynchronously. Slow handlers cause timeouts and unnecessary retries.

Return 2xx only once you’ve durably accepted the event (for example, written it to a queue or table). Returning 2xx before you’ve stored it means a crash loses the event — Ionic considers a 2xx an acknowledgment and won’t retry.

Test mode and live mode

Every event carries a livemode flag. Events generated by test API keys (sk_v1_test_…) have "livemode": false; events from live keys have "livemode": true. Endpoints are scoped to one mode — a test-mode endpoint only receives test-mode events. Build and verify your integration entirely in test mode before going live.

The envelope at a glance

Every delivery has the same outer shape. The event-specific data lives under data.object, which is the full resource snapshot — byte-for-byte the same shape the API returns from GET /v1/<resource>/{id}.

{
  "id": "evt_2pXq...",
  "type": "payment_intent.succeeded",
  "created": "2026-05-01T18:24:05Z",
  "livemode": true,
  "api_version": "2026-05-01",
  "operations": ["refund"],
  "data": {
    "object": {
      "id": "pi_2pXq...",
      "object": "payment_intent",
      "status": "succeeded",
      "amount": 5000,
      "currency": "USD"
    }
  }
}

See the envelope reference for every field, and the event catalog for a verified example of each event type.

Next steps

Quickstart

Verify signatures

Confirm every delivery really came from Ionic. Do this before trusting any event.

Event catalog

All 23 event types, when each fires, and a verified payload for each.

Idempotency & retries

Handle duplicates and out-of-order delivery correctly.

​How it works

​Delivery semantics

​Test mode and live mode

​The envelope at a glance

​Next steps

Quickstart

Verify signatures

Event catalog

Idempotency & retries

How it works

Delivery semantics

Test mode and live mode

The envelope at a glance

Next steps