> ## 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. # Rotate a webhook endpoint's signing secret > Generates a new signing secret for the endpoint. The new secret (`whsec_…`) is returned in this response and never again — store it immediately. The previous secret is revoked. Send an `Idempotency-Key` header. ## OpenAPI ````yaml /openapi/webhook_endpoints.yaml post /webhook_endpoints/{id}/rotate_secret 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/{id}/rotate_secret: parameters: - $ref: '#/components/parameters/WebhookEndpointId' post: tags: - Webhook Endpoints summary: Rotate a webhook endpoint's signing secret description: > Generates a new signing secret for the endpoint. The new secret (`whsec_…`) is returned in this response and never again — store it immediately. The previous secret is revoked. Send an `Idempotency-Key` header. operationId: webhook_endpoints_rotate_secret parameters: - $ref: '#/components/parameters/IdempotencyKeyRequired' responses: '200': description: The webhook endpoint with its new 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' '404': $ref: '#/components/responses/WebhookEndpointNotFound' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - secretKey: - webhook_endpoints:write components: parameters: WebhookEndpointId: name: id in: path required: true description: The webhook endpoint id (`whe_…`). schema: type: string 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: 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' WebhookEndpointNotFound: description: No webhook endpoint with that id is visible to this key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: WEBHOOK_ENDPOINT_NOT_FOUND message: webhook endpoint not found Conflict: description: The endpoint was modified concurrently; retry the request. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: CONFLICT message: webhook endpoint was modified concurrently 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 `.' ````