Skip to main content
POST
Error

Authorizations

Authorization
string
header
required

A merchant secret key (sk_…) sent as Authorization: Bearer <key>.

Headers

Idempotency-Key
string
required

Required. A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation.

Maximum string length: 255

Body

application/json
url
string
required

The HTTPS URL Ionic will POST event payloads to.

event_types
string[]
required

Event types to subscribe to. Each entry is one of:

  • an exact type, for example payment_intent.succeeded;
  • a resource wildcard, for example checkout.session.* (all events for that resource);
  • * to subscribe to every event.
description
string | null

Optional label for the endpoint.

api_version
string
default:2026-05-01

API version that pins the event payload shape delivered to this endpoint. Defaults to 2026-05-01.

Response

The created webhook endpoint, including its signing secret.

A webhook endpoint plus its signing secret (whsec_…) — returned only by create and rotate_secret. The secret is shown exactly once; store it immediately. No other response carries it.

id
string
required
object
enum<string>
required
Available options:
webhook_endpoint
merchant_id
string
required
livemode
boolean
required
url
string
required
description
string | null
required
event_types
string[]
required
api_version
string
required
status
enum<string>
required

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.

Available options:
active,
disabled,
deleted,
error
disabled
boolean
required

true when status is disabled; false otherwise.

created_at
integer
required

Unix epoch seconds.

updated_at
integer
required
secret
string
required

The signing secret for verifying deliveries. Shown exactly once, in this response.

secret_last_rotated_at
integer | null

Unix epoch seconds when the signing secret was last rotated. Null until the first rotation after creation.

deleted_at
integer | null

Unix epoch seconds when the endpoint was deleted. Null while active.