Webhooks

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, so 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.

SDKs

Resources

Webhooks

How it works

Delivery semantics

Test mode and live mode

The envelope at a glance

What’s next

Quickstart

Verify signatures

Event catalog

Idempotency and retries

​How it works

​Delivery semantics

​Test mode and live mode

​The envelope at a glance

​What’s next

Quickstart

Verify signatures

Event catalog

Idempotency and retries

How it works

Delivery semantics

Test mode and live mode

The envelope at a glance

What’s next