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

# The webhook endpoint object

> Register the URLs that receive your events and choose which event types they get.

<ResponseExample>
  ```json The webhook endpoint object theme={null}
  {
    "id": "whe_01JEXAMPLE2K8V4N9C6M1Q7R",
    "object": "webhook_endpoint",
    "url": "https://…",
    "scope": "account",
    "event_types": [],
    "api_version": "…",
    "status": "active",
    "disabled": false,
    "livemode": false
  }
  ```
</ResponseExample>

A webhook endpoint (`whe_…`) is an HTTPS URL plus the set of event types Ionic
delivers to it. You register an endpoint once, and Ionic sends each matching
event to it as a `POST`. Endpoints are scoped to one mode: a test key manages
test-mode endpoints and a live key manages live ones. To manage endpoints, see
[Manage endpoints](/webhooks/endpoints). To learn how deliveries work, see the
[webhooks overview](/webhooks/overview).

The signing secret (`whsec_…`) is returned only when you create an endpoint or
rotate its secret. Store it then. Use it to
[verify each delivery](/webhooks/signatures).

An endpoint's `scope` is its delivery stream, and it cannot change. `account`
delivers events for your own account. `connected_accounts` delivers events from
merchants connected to your platform. Ionic derives the scope from the
credential, so a platform credential creates a `connected_accounts` endpoint.
For platforms, create these endpoints without `Ionic-Account`. See
[Webhooks for platforms](/guides/connect-webhooks).

## Attributes

<ResponseField name="id" type="string">
  Unique identifier for the webhook endpoint (`whe_…`).
</ResponseField>

<ResponseField name="url" type="string">
  The HTTPS URL Ionic sends event payloads to.
</ResponseField>

<ResponseField name="scope" type="string">
  The immutable event stream delivered to this endpoint.
</ResponseField>

<ResponseField name="event_types" type="array of strings">
  Event types this endpoint receives, as exact types or wildcards.
</ResponseField>

<ResponseField name="api_version" type="string">
  API version that pins the event payload shape delivered to this endpoint.
</ResponseField>

<ResponseField name="status" type="string">
  Current lifecycle state. `active` means the endpoint is receiving deliveries. `disabled` means it is paused by the merchant. `deleted` means it has been soft-deleted. `error` means deliveries were disabled after repeated failures.
</ResponseField>

<ResponseField name="disabled" type="boolean">
  `true` when `status` is `disabled`; `false` otherwise.
</ResponseField>

See every field in the response of [Retrieve a webhook endpoint](/api-reference/webhook-endpoints/retrieve-a-webhook-endpoint).

## Endpoints

| Endpoint | Use it for |
| - | - |
| [Create a webhook endpoint](/api-reference/webhook-endpoints/create-a-webhook-endpoint) | Register a URL and subscribe it to event types. The response includes the signing secret. |
| [List webhook endpoints](/api-reference/webhook-endpoints/list-webhook-endpoints) | List the endpoints registered in this mode, newest first. |
| [Retrieve a webhook endpoint](/api-reference/webhook-endpoints/retrieve-a-webhook-endpoint) | Read one endpoint. |
| [Update a webhook endpoint](/api-reference/webhook-endpoints/update-a-webhook-endpoint) | Change the URL, description, event types, or status with `POST`. |
| [Update a webhook endpoint (PATCH)](/api-reference/webhook-endpoints/update-a-webhook-endpoint-patch) | Make the same changes with `PATCH`. |
| [Delete a webhook endpoint](/api-reference/webhook-endpoints/delete-a-webhook-endpoint) | Remove an endpoint permanently. |
| [Rotate a webhook endpoint's signing secret](/api-reference/webhook-endpoints/rotate-a-webhook-endpoints-signing-secret) | Issue a new signing secret and return it once. |

## Statuses

| Status | Meaning |
| - | - |
| `active` | The endpoint is receiving deliveries. |
| `disabled` | The endpoint is paused by the merchant. |
| `deleted` | The endpoint has been soft-deleted. |
| `error` | Deliveries were disabled after repeated failures. |

`disabled` is `true` when `status` is `disabled`, and `false` otherwise. To
pause an endpoint, set `disabled` to `true` or `status` to `disabled`. To
resume it, set `disabled` to `false` or `status` to `active`. Send only one of
the two fields in a request.

## Rules

* `event_types` accepts an exact type such as `payment_intent.succeeded`, a
  resource wildcard such as `checkout.session.*`, or `*` for every event. You
  can mix them in one array.
* Every write (create, update, delete, rotate) requires an `Idempotency-Key`
  header. Retrying with the same key and body returns the original response.
  See [Idempotency](/api-reference/idempotency).
* `api_version` pins the event payload shape for the endpoint. It defaults to
  `2026-05-01`.
* List and retrieve responses never include the signing secret.
* After a rotation, the previous secret keeps verifying for a brief overlap
  window.
* For connected accounts' events, delivery also requires an active Connection
  that grants the matching read permission. Registering an endpoint grants no
  resource access.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.