API Reference

Webhook Endpoints

Webhook endpoints are URLs on your server that receive event notifications from PaymentKit. Setting up a webhook endpoint allows your application to listen for asynchronous events, such as successful payments or subscription changes, and react to them in real-time. This is essential for building robust and reliable payment integrations.
For a conceptual overview of how to use webhooks effectively, see the Webhooks guide.
The Webhook Endpoint Object#A WebhookEndpoint object contains the configuration for a single webhook destination.
Attribute
Type
Description
id
string
Unique identifier for the webhook endpoint, prefixed with we_.
url
string
The URL where webhook events will be sent.
description
string
An optional description for the endpoint.
enabled_events
string[]
An array of event types that this endpoint is subscribed to.
status
string
The current status of the endpoint, either enabled or disabled.
metadata
object
A set of key-value pairs that you can attach to an object.
api_version
string
The API version used to render the event data sent to the endpoint.
livemode
boolean
true if the object exists in live mode, or false if it exists in test mode.
created_at
string
Timestamp of when the object was created.
updated_at
string
Timestamp of when the object was last updated.
Create an Endpoint#Registers a new URL to receive webhook events from PaymentKit.
Parameters#Name
Type
Description
url
string
Required. The URL for the webhook endpoint.
enabled_events
string[]
Required. The list of event types to receive. For example, ['payment_intent.succeeded'].
description
string
An optional description of the endpoint for your reference.
status
string
The status of the endpoint. Can be 'enabled' or 'disabled'. Defaults to 'enabled'.
metadata
object
A set of key-value pairs to store additional information about the object.
Returns#Returns the newly created WebhookEndpoint object.
Example#async function createWebhookEndpoint() {
  try {
    const endpoint = await payment.webhookEndpoints.create({
      url: 'https://example.com/webhooks/paymentkit',
      description: 'Webhook handler for production events',
      enabled_events: [
        'payment_intent.succeeded',
        'payment_intent.payment_failed',
        'customer.subscription.updated',
        'customer.subscription.deleted',
      ],
    });
    console.log('Webhook Endpoint Created:', endpoint);
  } catch (error) {
    console.error('Error creating webhook endpoint:', error.message);
  }
}

createWebhookEndpoint();Example Response#{
  "id": "we_1a2b3c4d5e6f7g8h9i0j",
  "url": "https://example.com/webhooks/paymentkit",
  "description": "Webhook handler for production events",
  "enabled_events": [
    "payment_intent.succeeded",
    "payment_intent.payment_failed",
    "customer.subscription.updated",
    "customer.subscription.deleted"
  ],
  "status": "enabled",
  "metadata": {},
  "api_version": "2023-09-05",
  "livemode": false,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}Retrieve an Endpoint#Fetches the details of a specific webhook endpoint by its ID.
Parameters#Name
Type
Description
id
string
Required. The unique identifier of the webhook endpoint to retrieve.
Returns#Returns the corresponding WebhookEndpoint object if found.
Example#async function retrieveWebhookEndpoint(endpointId) {
  try {
    const endpoint = await payment.webhookEndpoints.retrieve(endpointId);
    console.log('Retrieved Webhook Endpoint:', endpoint);
  } catch (error) {
    console.error('Error retrieving webhook endpoint:', error.message);
  }
}

retrieveWebhookEndpoint('we_1a2b3c4d5e6f7g8h9i0j');Example Response#{
  "id": "we_1a2b3c4d5e6f7g8h9i0j",
  "url": "https://example.com/webhooks/paymentkit",
  "description": "Webhook handler for production events",
  "enabled_events": [
    "payment_intent.succeeded",
    "payment_intent.payment_failed"
  ],
  "status": "enabled",
  "metadata": {},
  "api_version": "2023-09-05",
  "livemode": false,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:05:00.000Z"
}Update an Endpoint#Modifies an existing webhook endpoint's configuration.
Parameters#Name
Type
Description
id
string
Required. The identifier of the endpoint to update.
updates
object
Required. An object containing the fields to update.
Update Object Properties
Name
Type
Description
url
string
The new URL for the webhook endpoint.
description
string
An updated description for the endpoint.
enabled_events
string[]
A new list of event types to subscribe to. This will replace the existing list.
status
string
The new status, either 'enabled' or 'disabled'.
metadata
object
A set of key-value pairs to update. Existing metadata will be merged with the new values.
Returns#Returns the updated WebhookEndpoint object.
Example#async function updateWebhookEndpoint(endpointId) {
  try {
    const endpoint = await payment.webhookEndpoints.update(endpointId, {
      description: 'Updated webhook handler for production',
      status: 'disabled',
    });
    console.log('Webhook Endpoint Updated:', endpoint);
  } catch (error) {
    console.error('Error updating webhook endpoint:', error.message);
  }
}

updateWebhookEndpoint('we_1a2b3c4d5e6f7g8h9i0j');Example Response#{
  "id": "we_1a2b3c4d5e6f7g8h9i0j",
  "url": "https://example.com/webhooks/paymentkit",
  "description": "Updated webhook handler for production",
  "enabled_events": [
    "payment_intent.succeeded",
    "payment_intent.payment_failed"
  ],
  "status": "disabled",
  "metadata": {},
  "api_version": "2023-09-05",
  "livemode": false,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:15:00.000Z"
}List Endpoints#Retrieves a paginated list of all your webhook endpoints.
Parameters#Name
Type
Description
status
string
A comma-separated string to filter endpoints by status (e.g., 'enabled', 'disabled').
metadata.{key}
string
Filter by a key-value pair in the metadata. For example, metadata.team_id: 'abc-123'.
page
number
The page number for pagination. Defaults to 1.
pageSize
number
The number of endpoints to return per page. Defaults to 20.
order
string
The order to sort the results. For example, 'created_at:DESC'.
Returns#Returns a paginated object containing a list of WebhookEndpoint objects, a count of total items, and a paging object.
Example#async function listWebhookEndpoints() {
  try {
    const results = await payment.webhookEndpoints.list({
      status: 'enabled',
      pageSize: 5,
    });
    console.log(`Found ${results.count} enabled endpoints.`);
    results.list.forEach(endpoint => {
      console.log(`- ${endpoint.id} -> ${endpoint.url}`);
    });
  } catch (error) {
    console.error('Error listing webhook endpoints:', error.message);
  }
}

listWebhookEndpoints();Example Response#{
  "count": 1,
  "list": [
    {
      "id": "we_1a2b3c4d5e6f7g8h9i0j",
      "url": "https://example.com/webhooks/paymentkit",
      "description": "Webhook handler for production events",
      "enabled_events": ["payment_intent.succeeded"],
      "status": "enabled",
      "metadata": {},
      "api_version": "2023-09-05",
      "livemode": false,
      "created_at": "2023-10-27T10:00:00.000Z",
      "updated_at": "2023-10-27T10:00:00.000Z"
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}Delete an Endpoint#Permanently removes a webhook endpoint. This action cannot be undone.
Parameters#Name
Type
Description
id
string
Required. The identifier of the webhook endpoint to delete.
Returns#Returns the deleted WebhookEndpoint object.
Example#async function deleteWebhookEndpoint(endpointId) {
  try {
    const deletedEndpoint = await payment.webhookEndpoints.del(endpointId);
    console.log('Webhook Endpoint Deleted:', deletedEndpoint.id);
  } catch (error) {
    console.error('Error deleting webhook endpoint:', error.message);
  }
}

deleteWebhookEndpoint('we_1a2b3c4d5e6f7g8h9i0j');Example Response#{
  "id": "we_1a2b3c4d5e6f7g8h9i0j",
  "url": "https://example.com/webhooks/paymentkit",
  "description": "Updated webhook handler for production",
  "enabled_events": [
    "payment_intent.succeeded",
    "payment_intent.payment_failed"
  ],
  "status": "disabled",
  "metadata": {},
  "api_version": "2023-09-05",
  "livemode": false,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:15:00.000Z"
}
After configuring your webhook endpoints, you may want to manage your account-level configurations. See the Settings API for more details.

Attribute	Type	Description
`id`	`string`	Unique identifier for the webhook endpoint, prefixed with `we_`.
`url`	`string`	The URL where webhook events will be sent.
`description`	`string`	An optional description for the endpoint.
`enabled_events`	`string[]`	An array of event types that this endpoint is subscribed to.
`status`	`string`	The current status of the endpoint, either `enabled` or `disabled`.
`metadata`	`object`	A set of key-value pairs that you can attach to an object.
`api_version`	`string`	The API version used to render the event data sent to the endpoint.
`livemode`	`boolean`	`true` if the object exists in live mode, or `false` if it exists in test mode.
`created_at`	`string`	Timestamp of when the object was created.
`updated_at`	`string`	Timestamp of when the object was last updated.

Name	Type	Description
`url`	`string`	Required. The URL for the webhook endpoint.
`enabled_events`	`string[]`	Required. The list of event types to receive. For example, `['payment_intent.succeeded']`.
`description`	`string`	An optional description of the endpoint for your reference.
`status`	`string`	The status of the endpoint. Can be `'enabled'` or `'disabled'`. Defaults to `'enabled'`.
`metadata`	`object`	A set of key-value pairs to store additional information about the object.

Name	Type	Description
`id`	`string`	Required. The identifier of the endpoint to update.
`updates`	`object`	Required. An object containing the fields to update.

Name	Type	Description
`url`	`string`	The new URL for the webhook endpoint.
`description`	`string`	An updated description for the endpoint.
`enabled_events`	`string[]`	A new list of event types to subscribe to. This will replace the existing list.
`status`	`string`	The new status, either `'enabled'` or `'disabled'`.
`metadata`	`object`	A set of key-value pairs to update. Existing metadata will be merged with the new values.

Name	Type	Description
`status`	`string`	A comma-separated string to filter endpoints by status (e.g., `'enabled'`, `'disabled'`).
`metadata.{key}`	`string`	Filter by a key-value pair in the metadata. For example, `metadata.team_id: 'abc-123'`.
`page`	`number`	The page number for pagination. Defaults to `1`.
`pageSize`	`number`	The number of endpoints to return per page. Defaults to `20`.
`order`	`string`	The order to sort the results. For example, `'created_at:DESC'`.

Overview

Getting Started

SDK Structure

Environments

Core Concepts

API Reference

Webhook Endpoints

The Webhook Endpoint Object#

Create an Endpoint#

Parameters#

Returns#

Example#

Example Response#

Retrieve an Endpoint#

Parameters#

Returns#

Example#

Example Response#

Update an Endpoint#

Parameters#

Returns#

Example#

Example Response#

List Endpoints#

Parameters#

Returns#

Example#

Example Response#

Delete an Endpoint#

Parameters#

Returns#

Example#

Example Response#

Credit Transactions

Settings