> ## 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. # Create a webhook endpoint > Registers a new endpoint at the given URL and subscribes it to the specified event types. The signing secret (`whsec_…`) is returned in this response and never again — store it immediately. Send an `Idempotency-Key` header to make the request safe to retry. ## OpenAPI ````yaml /openapi/webhook_endpoints.yaml post /webhook_endpoints openapi: 3.0.3 info: title: Ionic Webhook Endpoints API version: '2026-05-01' description: > Webhook endpoints — HTTPS destinations that receive event notifications when resources change. A webhook endpoint (`whe_…`) pairs a URL with a set of subscribed event types. When a subscribed event occurs, Ionic delivers a signed HTTP POST to that URL with the event payload. You can subscribe to exact event types (for example `payment_intent.succeeded`), to all events for a resource using a wildcard (`checkout.session.*`), or to every event with `*`. Each endpoint carries a signing secret (`whsec_…`) you use to verify that deliveries come from Ionic. The secret is returned exactly once: in the create response and in the rotate_secret response. It is not included in retrieve, list, or update responses. Store it securely; it is not retrievable afterwards. Timestamps are Unix epoch seconds. Identifiers are opaque, prefixed strings. Authentication uses a merchant secret key (`sk_…`) as a bearer token. Read endpoints require the `webhook_endpoints:read` permission; write endpoints require `webhook_endpoints:write`. The mode of the key (test or live) scopes which endpoints it can see and mutate, reflected by each endpoint's `livemode` field. All write operations require an `Idempotency-Key` header. Errors are returned as `{ "error": { "code": "...", "message": "..." } }`. servers: - url: '{baseUrl}/v1' variables: baseUrl: default: https://api.ionicfi.com description: API base URL for your environment. security: - secretKey: [] tags: - name: Webhook Endpoints description: Register and manage HTTPS destinations that receive event notifications. paths: /webhook_endpoints: post: tags: - Webhook Endpoints summary: Create a webhook endpoint description: > Registers a new endpoint at the given URL and subscribes it to the specified event types. The signing secret (`whsec_…`) is returned in this response and never again — store it immediately. Send an `Idempotency-Key` header to make the request safe to retry. operationId: webhook_endpoints_create parameters: - $ref: '#/components/parameters/IdempotencyKeyRequired' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWebhookEndpointRequest' responses: '201': description: The created webhook endpoint, including its signing secret. content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointWithSecret' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - secretKey: - webhook_endpoints:write components: parameters: IdempotencyKeyRequired: name: Idempotency-Key in: header required: true description: >- 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. schema: type: string maxLength: 255 schemas: CreateWebhookEndpointRequest: type: object required: - url - event_types properties: url: type: string description: The HTTPS URL Ionic will POST event payloads to. event_types: type: array items: type: string description: > 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: type: string nullable: true description: Optional label for the endpoint. api_version: type: string description: >- API version that pins the event payload shape delivered to this endpoint. Defaults to `2026-05-01`. default: '2026-05-01' WebhookEndpointWithSecret: description: >- 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. allOf: - $ref: '#/components/schemas/WebhookEndpoint' - type: object required: - secret properties: secret: type: string description: >- The signing secret for verifying deliveries. Shown exactly once, in this response. WebhookEndpoint: type: object required: - api_version - created_at - description - disabled - event_types - id - livemode - merchant_id - object - status - updated_at - url properties: id: type: string object: type: string enum: - webhook_endpoint merchant_id: type: string livemode: type: boolean url: type: string description: type: string nullable: true event_types: type: array items: type: string api_version: type: string status: type: string enum: - active - disabled - deleted - error description: > 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. disabled: type: boolean description: '`true` when `status` is `disabled`; `false` otherwise.' secret_last_rotated_at: type: integer nullable: true description: >- Unix epoch seconds when the signing secret was last rotated. Null until the first rotation after creation. created_at: type: integer description: Unix epoch seconds. updated_at: type: integer deleted_at: type: integer nullable: true description: Unix epoch seconds when the endpoint was deleted. Null while active. Error: type: object properties: error: type: object properties: code: type: string description: A stable, machine-readable error code. message: type: string responses: BadRequest: description: The request was malformed or failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_REQUEST message: url is required Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The key lacks the required permission, or the merchant is not active. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: Too many requests. Honour the `Retry-After` header before retrying. content: application/json: schema: $ref: '#/components/schemas/Error' InternalError: description: | The API could not return a successful response. For a mutating request, retrieve the resource before retrying because the operation may have completed. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: secretKey: type: http scheme: bearer description: 'A merchant secret key (`sk_…`) sent as `Authorization: Bearer `.' ````