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#

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#

{
  "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#

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#

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#

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#

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.