Webhook Endpoints

Webhook endpoints allow PaymentKit to send asynchronous event notifications to your server. This is essential for handling events like successful payments, subscription updates, or failed charges. By creating and managing webhook endpoints, you can ensure your application stays in sync with the state of your payments and customers.

For a conceptual overview and best practices on securing your webhooks, please refer to our guide on Webhooks.

Create a Webhook Endpoint

Creates a new endpoint for receiving webhook events from PaymentKit.

Parameters

Name	Type	Description	Required
`url`	`string`	The URL of your server that will receive the webhook POST requests.	Yes
`enabled_events`	`string[]`	An array of event types that you want to send to this endpoint.	Yes
`description`	`string`	An optional description for the webhook endpoint.	No
`status`	`'enabled' \| 'disabled'`	Optional. The status of the endpoint. If not provided, it defaults to `enabled`.	No
`metadata`	`Record<string, any>`	Optional. A set of key-value pairs that you can attach to the object for your own reference.	No

Returns

Returns the created WebhookEndpoint object if the call is successful.

Example

Create Endpoint

async function createWebhookEndpoint() {
  try {
    const endpoint = await payment.webhookEndpoints.create({
      url: 'https://example.com/my/webhook/handler',
      enabled_events: [
        'checkout.session.completed',
        'customer.subscription.updated',
      ],
      description: 'Endpoint for production events',
    });
    console.log('Webhook Endpoint Created:', endpoint);
  } catch (error) {
    console.error('Error creating webhook endpoint:', error.message);
  }
}

createWebhookEndpoint();

Example Response

Response

{
  "id": "we_1a2b3c4d5e6f7g8h",
  "url": "https://example.com/my/webhook/handler",
  "description": "Endpoint for production events",
  "enabled_events": [
    "checkout.session.completed",
    "customer.subscription.updated"
  ],
  "status": "enabled",
  "api_version": "2023-09-05",
  "livemode": false,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "metadata": {}
}

Retrieve a Webhook Endpoint

Retrieves the details of an existing webhook endpoint by its unique identifier.

Parameters

Name	Type	Description	Required
`id`	`string`	The unique identifier of the webhook endpoint.	Yes

Returns

Returns the WebhookEndpoint object corresponding to the provided ID.

Example

Retrieve Endpoint

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_1a2b3c4d5e6f7g8h');

Update a Webhook Endpoint

Updates an existing webhook endpoint by setting the values of the parameters passed.

Parameters

Name	Type	Description	Required
`id`	`string`	The identifier of the webhook endpoint to update.	Yes
`url`	`string`	The URL of your server that will receive the webhook POST requests.	No
`description`	`string`	An optional description for the webhook endpoint.	No
`enabled_events`	`string[]`	An array of event types that you want to send to this endpoint.	No
`status`	`'enabled' \| 'disabled'`	The status of the endpoint. Use `disabled` to temporarily stop sending events.	No
`metadata`	`Record<string, any>`	A set of key-value pairs that you can attach to the object.	No

Returns

Returns the updated WebhookEndpoint object.

Example

Update Endpoint

async function updateWebhookEndpoint(endpointId) {
  try {
    const endpoint = await payment.webhookEndpoints.update(endpointId, {
      description: 'New updated description',
      status: 'disabled',
    });
    console.log('Webhook Endpoint Updated:', endpoint);
  } catch (error) {
    console.error('Error updating webhook endpoint:', error.message);
  }
}

updateWebhookEndpoint('we_1a2b3c4d5e6f7g8h');

List all Webhook Endpoints

Returns a paginated list of all your webhook endpoints.

Parameters

Name	Type	Description	Required
`status`	`string`	Optional. A comma-separated list of statuses to filter by (e.g., `'enabled'` or `'enabled,disabled'`).	No
`page`	`number`	Optional. The page number for pagination, starting from 1. Defaults to `1`.	No
`pageSize`	`number`	Optional. The number of items to return per page, between 1 and 100. Defaults to `20`.	No

Returns

Returns a paginated object containing a list of WebhookEndpoint objects, a count of total items, and paging information.

Example

List Endpoints

async function listWebhookEndpoints() {
  try {
    const endpoints = await payment.webhookEndpoints.list({
      status: 'enabled',
      pageSize: 5,
    });
    console.log(`Found ${endpoints.count} enabled endpoints:`);
    endpoints.list.forEach(ep => console.log(`- ${ep.id} (${ep.url})`));
  } catch (error) {
    console.error('Error listing webhook endpoints:', error.message);
  }
}

listWebhookEndpoints();

Delete a Webhook Endpoint

Permanently deletes a webhook endpoint. This action is irreversible.

Parameters

Name	Type	Description	Required
`id`	`string`	The unique identifier of the webhook endpoint to delete.	Yes

Returns

Returns the deleted WebhookEndpoint object.

Example

Delete Endpoint

async function deleteWebhookEndpoint(endpointId) {
  try {
    const deletedEndpoint = await payment.webhookEndpoints.del(endpointId);
    console.log('Webhook Endpoint Deleted:', deletedEndpoint);
  } catch (error) {
    console.error('Error deleting webhook endpoint:', error.message);
  }
}

deleteWebhookEndpoint('we_1a2b3c4d5e6f7g8h');

The Webhook Endpoint Object

The WebhookEndpoint object represents a configured destination for event notifications.

Attribute	Type	Description
`id`	`string`	Unique identifier for the webhook endpoint object.
`url`	`string`	The endpoint's URL for receiving webhook POST requests.
`description`	`string`	An optional, user-provided description of the endpoint.
`enabled_events`	`string[]`	The list of event types this endpoint is subscribed to.
`status`	`string`	The current status of the webhook endpoint (`enabled` or `disabled`).
`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 in test mode.
`metadata`	`object`	A set of key-value pairs attached to the object.
`created_at`	`string`	An ISO 8601 timestamp indicating when the object was created.
`updated_at`	`string`	An ISO 8601 timestamp indicating when the object was last updated.