> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive events from Ionic when something happens in your account.

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

<Steps>
  <Step title="Register an endpoint">
    Tell Ionic which URL to deliver to with [`POST /v1/webhook_endpoints`](/webhooks/endpoints). You receive a signing secret once, at creation time.
  </Step>

  <Step title="Receive events">
    Ionic sends each event as a `POST` with a JSON [envelope](/webhooks/envelope) in the body. Respond `2xx` quickly to acknowledge receipt.
  </Step>

  <Step title="Verify and act">
    [Verify the signature](/webhooks/signatures) on every request, then act on the event — idempotently, because the same event can arrive more than once.
  </Step>
</Steps>

## 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](/webhooks/idempotency-and-retries) 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.                             |

<Warning>
  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.
</Warning>

## 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}`.

```json theme={null}
{
  "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](/webhooks/envelope) for every field, and the [event catalog](/webhooks/events) for a verified example of each event type.

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="play" href="/webhooks/quickstart">
    Register an endpoint and verify your first event in about five minutes.
  </Card>

  <Card title="Verify signatures" icon="shield-halved" href="/webhooks/signatures">
    Confirm every delivery really came from Ionic. Do this before trusting any event.
  </Card>

  <Card title="Event catalog" icon="list" href="/webhooks/events">
    All 23 event types, when each fires, and a verified payload for each.
  </Card>

  <Card title="Idempotency & retries" icon="arrows-rotate" href="/webhooks/idempotency-and-retries">
    Handle duplicates and out-of-order delivery correctly.
  </Card>
</CardGroup>