Webhook endpoints

The webhook endpoints endpoints of the Kashu API, with their parameters, objects, errors and examples. The guide explains how they fit together.

Endpoint	What it does
POST `/v1/webhook_endpoints`	Create a webhook endpoint. The response is the only place its signing secret appears.
GET `/v1/webhook_endpoints`	List the webhook endpoints of the calling key's mode, newest first.
GET `/v1/webhook_endpoints/{id}`	Retrieve a webhook endpoint.
POST `/v1/webhook_endpoints/{id}`	Update a webhook endpoint: its URL, description and event types, or disable and enable it.
DELETE `/v1/webhook_endpoints/{id}`	Delete a webhook endpoint. Kashu sends it nothing more.
POST `/v1/webhook_endpoints/{id}/roll`	Replace the endpoint's signing secret at once. The response is the only place the new secret appears.

The webhook endpoint object

Field	Type	About
`id`	string	An id that starts `we_`.
`object`	string	Always `"webhook_endpoint"`.
`url`	string
`description`	string or null
`enabled_events`	array of enum	One of `*`, `customer.created`, `customer.updated`, `payment.created`, `payment.updated`, `payment.requires_action`, `payment.requires_capture`, `payment.succeeded`, `payment.failed`, `payment.canceled`, `refund.created`, `refund.succeeded`, `refund.failed`, `subscription.created`, `subscription.updated`, `subscription.canceled`, `dispute.created`, `dispute.updated`, `checkout.session.completed`, `checkout.session.expired`.
`status`	enum	One of `enabled`, `disabled`.
`disabled_reason`	enum or null	One of `requested`, `failing`.
`api_version`	enum	One of `2026-11-06`.
`secret`	string
`secret_last4`	string
`livemode`	boolean
`created`	integer	Unix seconds.

{
  "id": "we_1a2B3c4D5e6F7g8H9i0J1k2L",
  "object": "webhook_endpoint",
  "url": "https://shop.example.com/kashu/webhooks",
  "description": "Order 1001",
  "enabled_events": [
    "customer.created"
  ],
  "status": "enabled",
  "disabled_reason": null,
  "api_version": "2026-11-06",
  "secret_last4": "aaaa",
  "livemode": false,
  "created": 1762473600
}

The deleted webhook endpoint object

Field	Type	About
`id`	string	An id that starts `we_`.
`object`	string	Always `"webhook_endpoint"`.
`deleted`	boolean	Always `true`.

{
  "id": "we_1a2B3c4D5e6F7g8H9i0J1k2L",
  "object": "webhook_endpoint",
  "deleted": true
}

POST `/v1/webhook_endpoints`

Create a webhook endpoint. The response is the only place its signing secret appears.

Scope: webhook_endpoints:write
Keys: Secret, or restricted with the scope below.
Idempotency-Key: Optional. Without one, Kashu makes one and returns it. See Idempotency.
Answers: 201 with the Webhook endpoint.

Parameters

Name	In	Type	Required	About
`Idempotency-Key`	header	string	Optional	Optional. When absent, Kashu mints one and returns it. Up to 255 characters.
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Request body

Field	Type	Required	About
`url`	string	Required	Up to 2048 characters.
`enabled_events`	array of enum	Required	One of `*`, `customer.created`, `customer.updated`, `payment.created`, `payment.updated`, `payment.requires_action`, `payment.requires_capture`, `payment.succeeded`, `payment.failed`, `payment.canceled`, `refund.created`, `refund.succeeded`, `refund.failed`, `subscription.created`, `subscription.updated`, `subscription.canceled`, `dispute.created`, `dispute.updated`, `checkout.session.completed`, `checkout.session.expired`. Up to 20 items.
`description`	string	Optional	Up to 200 characters.

Errors

Status	Codes
400	`invalid_json`, `parameter_missing`, `parameter_invalid`, `parameter_unknown`, `api_version_invalid`, `idempotency_key_invalid`, `idempotency_key_reused`, `webhook_endpoint_limit`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `publishable_key_not_allowed`
409	`idempotency_key_in_use`
429	`rate_limited`
500	`api_error`

Examples

curl https://api.kashupay.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $KASHU_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://shop.example.com/kashu/webhooks","enabled_events":["customer.created"]}'

const webhookEndpoint = await kashu("POST", "/v1/webhook_endpoints", {
  "url": "https://shop.example.com/kashu/webhooks",
  "enabled_events": [
    "customer.created"
  ]
});
console.log(webhookEndpoint.status);

GET `/v1/webhook_endpoints`

List the webhook endpoints of the calling key's mode, newest first.

Scope: webhook_endpoints:read
Keys: Secret, or restricted with the scope below.
Idempotency-Key: Not used. A read changes nothing.
Answers: 200 with a list of Webhook endpoint, newest first.

Parameters

Name	In	Type	Required	About
`limit`	query	integer	Optional	At least 1. Up to 100. Defaults to `10`.
`cursor`	query	string	Optional
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Errors

Status	Codes
400	`parameter_missing`, `parameter_invalid`, `parameter_unknown`, `cursor_invalid`, `cursor_expired`, `api_version_invalid`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `publishable_key_not_allowed`
500	`api_error`

Examples

curl "https://api.kashupay.com/v1/webhook_endpoints?limit=3" \
  -H "Authorization: Bearer $KASHU_SECRET_KEY"

const list = await kashu("GET", "/v1/webhook_endpoints?limit=3");
console.log(list.has_more);

GET `/v1/webhook_endpoints/{id}`

Retrieve a webhook endpoint.

Scope: webhook_endpoints:read
Keys: Secret, or restricted with the scope below.
Idempotency-Key: Not used. A read changes nothing.
Answers: 200 with the Webhook endpoint.

Parameters

Name	In	Type	Required	About
`id`	path	string	Required	An id that starts `we_`.
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Errors

Status	Codes
400	`parameter_unknown`, `api_version_invalid`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `publishable_key_not_allowed`
404	`resource_missing`
500	`api_error`

Examples

curl https://api.kashupay.com/v1/webhook_endpoints/we_1a2B3c4D5e6F7g8H9i0J1k2L \
  -H "Authorization: Bearer $KASHU_SECRET_KEY"

const webhookEndpoint = await kashu("GET", "/v1/webhook_endpoints/we_1a2B3c4D5e6F7g8H9i0J1k2L");
console.log(webhookEndpoint.status);

POST `/v1/webhook_endpoints/{id}`

Update a webhook endpoint: its URL, description and event types, or disable and enable it.

Scope: webhook_endpoints:write
Keys: Secret, or restricted with the scope below.
Idempotency-Key: Optional. Without one, Kashu makes one and returns it. See Idempotency.
Answers: 200 with the Webhook endpoint.

Parameters

Name	In	Type	Required	About
`id`	path	string	Required	An id that starts `we_`.
`Idempotency-Key`	header	string	Optional	Optional. When absent, Kashu mints one and returns it. Up to 255 characters.
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Request body

Field	Type	Required	About
`url`	string	Optional	Up to 2048 characters.
`enabled_events`	array of enum	Optional	One of `*`, `customer.created`, `customer.updated`, `payment.created`, `payment.updated`, `payment.requires_action`, `payment.requires_capture`, `payment.succeeded`, `payment.failed`, `payment.canceled`, `refund.created`, `refund.succeeded`, `refund.failed`, `subscription.created`, `subscription.updated`, `subscription.canceled`, `dispute.created`, `dispute.updated`, `checkout.session.completed`, `checkout.session.expired`. Up to 20 items.
`description`	string or null	Optional	Up to 200 characters.
`disabled`	boolean	Optional

Errors

Status	Codes
400	`invalid_json`, `parameter_missing`, `parameter_invalid`, `parameter_unknown`, `api_version_invalid`, `idempotency_key_invalid`, `idempotency_key_reused`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `publishable_key_not_allowed`
404	`resource_missing`
409	`idempotency_key_in_use`
429	`rate_limited`
500	`api_error`

Examples

curl https://api.kashupay.com/v1/webhook_endpoints/we_1a2B3c4D5e6F7g8H9i0J1k2L \
  -H "Authorization: Bearer $KASHU_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"disabled":false}'

const webhookEndpoint = await kashu("POST", "/v1/webhook_endpoints/we_1a2B3c4D5e6F7g8H9i0J1k2L", {
  "disabled": false
});
console.log(webhookEndpoint.status);

DELETE `/v1/webhook_endpoints/{id}`

Delete a webhook endpoint. Kashu sends it nothing more.

Scope: webhook_endpoints:write
Keys: Secret, or restricted with the scope below.
Idempotency-Key: Optional. Without one, Kashu makes one and returns it. See Idempotency.
Answers: 200 with the Deleted webhook endpoint.

Parameters

Name	In	Type	Required	About
`id`	path	string	Required	An id that starts `we_`.
`Idempotency-Key`	header	string	Optional	Optional. When absent, Kashu mints one and returns it. Up to 255 characters.
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Request body

Send no body, or an empty JSON object.

Errors

Status	Codes
400	`invalid_json`, `parameter_unknown`, `api_version_invalid`, `idempotency_key_invalid`, `idempotency_key_reused`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `publishable_key_not_allowed`
404	`resource_missing`
409	`idempotency_key_in_use`
429	`rate_limited`
500	`api_error`

Examples

curl https://api.kashupay.com/v1/webhook_endpoints/we_1a2B3c4D5e6F7g8H9i0J1k2L \
  -X DELETE \
  -H "Authorization: Bearer $KASHU_SECRET_KEY"

const deleted = await kashu("DELETE", "/v1/webhook_endpoints/we_1a2B3c4D5e6F7g8H9i0J1k2L");
console.log(deleted.id);

POST `/v1/webhook_endpoints/{id}/roll`

Replace the endpoint's signing secret at once. The response is the only place the new secret appears.

Scope: webhook_endpoints:write
Keys: Secret, or restricted with the scope below.
Idempotency-Key: Optional. Without one, Kashu makes one and returns it. See Idempotency.
Answers: 200 with the Webhook endpoint.

Parameters

Name	In	Type	Required	About
`id`	path	string	Required	An id that starts `we_`.
`Idempotency-Key`	header	string	Optional	Optional. When absent, Kashu mints one and returns it. Up to 255 characters.
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Request body

Send no body, or an empty JSON object.

Errors

Status	Codes
400	`invalid_json`, `parameter_unknown`, `api_version_invalid`, `idempotency_key_invalid`, `idempotency_key_reused`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `publishable_key_not_allowed`
404	`resource_missing`
409	`idempotency_key_in_use`
429	`rate_limited`
500	`api_error`

Examples

curl https://api.kashupay.com/v1/webhook_endpoints/we_1a2B3c4D5e6F7g8H9i0J1k2L/roll \
  -X POST \
  -H "Authorization: Bearer $KASHU_SECRET_KEY"

const webhookEndpoint = await kashu("POST", "/v1/webhook_endpoints/we_1a2B3c4D5e6F7g8H9i0J1k2L/roll");
console.log(webhookEndpoint.status);

Webhook endpoints

The webhook endpoint object

The deleted webhook endpoint object

POST /v1/webhook_endpoints

Parameters

Request body

Errors

Examples

GET /v1/webhook_endpoints

Parameters

Errors

Examples

GET /v1/webhook_endpoints/{id}

Parameters

Errors

Examples

POST /v1/webhook_endpoints/{id}

Parameters

Request body

Errors

Examples

DELETE /v1/webhook_endpoints/{id}

Parameters

Request body

Errors

Examples

POST /v1/webhook_endpoints/{id}/roll

Parameters

Request body

Errors

Examples

POST `/v1/webhook_endpoints`

GET `/v1/webhook_endpoints`

GET `/v1/webhook_endpoints/{id}`

POST `/v1/webhook_endpoints/{id}`

DELETE `/v1/webhook_endpoints/{id}`

POST `/v1/webhook_endpoints/{id}/roll`