API Reference

Webhooks

Webhooks are a powerful tool for receiving real-time notifications about events happening in your PaymentKit account, such as successful payments, subscription updates, or failed charges. By setting up a webhook endpoint, you can automate your backend processes in response to these events.
This document provides a detailed reference for the Webhook Endpoints API. For a higher-level guide on how to implement and secure webhooks, please see the Webhooks guide.
The Webhook Endpoint Object#A webhook endpoint object contains information about the URL to be notified and the specific events it should listen for.
Attribute
Type
Description
id
string
Unique identifier for the webhook endpoint.
livemode
boolean
true if the object exists in live mode, or false if it exists in test mode.
api_version
string
The API version used to render the event data sent to the endpoint.
url
string
The URL of the webhook endpoint.
description
string
An optional description of the webhook endpoint.
enabled_events
string[]
The list of event types that this endpoint is configured to receive. Examples include 'charge.succeeded', 'customer.subscription.created'.
metadata
object
A set of key-value pairs that you can attach to an object. Useful for storing additional information.
status
string
The status of the webhook endpoint, can be either 'enabled' or 'disabled'.
created_at
Date
Timestamp of when the object was created.
created_via
string
How the endpoint was created, either 'api', 'dashboard', or 'portal'.
updated_at
Date
Timestamp of the last update.
Create a Webhook Endpoint#Creates a new webhook endpoint to receive notifications.
Parameters
Name
Type
Description
url
string
Required. The URL where event notifications will be sent via POST request.
enabled_events
string[]
Required. An array of event type strings that you want to subscribe to.
description
string
An optional description for the endpoint.
api_version
string
The API version for the event data. Defaults to your account's default API version.
metadata
object
Optional key-value data to store with the endpoint.
status
string
The initial status of the endpoint. Can be 'enabled' or 'disabled'. Defaults to 'enabled'.
Returns
Returns the newly created webhook endpoint object.
import payment from '@blocklet/payment-js';

async function createWebhookEndpoint() {
  try {
    const endpoint = await payment.webhooks.create({
      url: 'https://example.com/webhook-receiver',
      enabled_events: [
        'charge.succeeded',
        'customer.subscription.deleted'
      ],
      description: 'Endpoint for production events'
    });
    console.log('Webhook endpoint created:', endpoint.id);
    return endpoint;
  } catch (error) {
    console.error('Error creating webhook endpoint:', error.message);
  }
}

createWebhookEndpoint();Example Response
{
  "id": "whep_123456789",
  "livemode": false,
  "api_version": "2024-01-01",
  "url": "https://example.com/webhook-receiver",
  "description": "Endpoint for production events",
  "enabled_events": [
    "charge.succeeded",
    "customer.subscription.deleted"
  ],
  "metadata": {},
  "status": "enabled",
  "created_at": "2024-05-21T10:00:00.000Z",
  "created_via": "api",
  "updated_at": "2024-05-21T10:00:00.000Z"
}Retrieve a Webhook Endpoint#Retrieves the details of an existing webhook endpoint by its ID.
Parameters
Name
Type
Description
id
string
Required. The unique identifier of the webhook endpoint to retrieve.
Returns
Returns the specified webhook endpoint object.
import payment from '@blocklet/payment-js';

async function retrieveWebhookEndpoint(endpointId) {
  try {
    const endpoint = await payment.webhooks.retrieve(endpointId);
    console.log('Retrieved endpoint:', endpoint.url);
    return endpoint;
  } catch (error) {
    console.error(`Error retrieving webhook endpoint ${endpointId}:`, error.message);
  }
}

retrieveWebhookEndpoint('whep_123456789');Example Response
{
  "id": "whep_123456789",
  "livemode": false,
  "api_version": "2024-01-01",
  "url": "https://example.com/webhook-receiver",
  "description": "Endpoint for production events",
  "enabled_events": [
    "charge.succeeded",
    "customer.subscription.deleted"
  ],
  "metadata": {},
  "status": "enabled",
  "created_at": "2024-05-21T10:00:00.000Z",
  "created_via": "api",
  "updated_at": "2024-05-21T10:00:00.000Z"
}Update a Webhook Endpoint#Updates an existing webhook endpoint. You can change its URL, the events it listens for, its description, or its status.
Parameters
Name
Type
Description
id
string
Required. The identifier of the endpoint to update.
url
string
The new URL for the endpoint.
enabled_events
string[]
The new list of event types to subscribe to. This will replace the existing list.
description
string
An updated description.
status
string
The new status, either 'enabled' or 'disabled'.
metadata
object
New metadata. This will replace the existing metadata.
Returns
Returns the updated webhook endpoint object.
import payment from '@blocklet/payment-js';

async function updateWebhookEndpoint(endpointId) {
  try {
    const endpoint = await payment.webhooks.update(endpointId, {
      description: 'Updated endpoint description',
      status: 'disabled'
    });
    console.log('Webhook endpoint updated:', endpoint.id, 'Status:', endpoint.status);
    return endpoint;
  } catch (error) {
    console.error(`Error updating webhook endpoint ${endpointId}:`, error.message);
  }
}

updateWebhookEndpoint('whep_123456789');Example Response
{
  "id": "whep_123456789",
  "livemode": false,
  "api_version": "2024-01-01",
  "url": "https://example.com/webhook-receiver",
  "description": "Updated endpoint description",
  "enabled_events": [
    "charge.succeeded",
    "customer.subscription.deleted"
  ],
  "metadata": {},
  "status": "disabled",
  "created_at": "2024-05-21T10:00:00.000Z",
  "created_via": "api",
  "updated_at": "2024-05-21T10:05:00.000Z"
}List all Webhook Endpoints#Returns a paginated list of all your webhook endpoints.
Parameters
Name
Type
Description
page
number
The page number for pagination, starting from 1.
pageSize
number
The number of items to return per page. Defaults to 20.
order
`string
string[]`
Returns
Returns a paginated object containing a list of webhook endpoints.
Name
Type
Description
count
number
The total number of endpoints matching the query.
list
object[]
An array of webhook endpoint objects.
import payment from '@blocklet/payment-js';

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

listWebhookEndpoints();Example Response
{
  "count": 1,
  "list": [
    {
      "id": "whep_123456789",
      "livemode": false,
      "api_version": "2024-01-01",
      "url": "https://example.com/webhook-receiver",
      "description": "Updated endpoint description",
      "enabled_events": [
        "charge.succeeded",
        "customer.subscription.deleted"
      ],
      "metadata": {},
      "status": "disabled",
      "created_at": "2024-05-21T10:00:00.000Z",
      "created_via": "api",
      "updated_at": "2024-05-21T10:05:00.000Z"
    }
  ]
}Delete a Webhook Endpoint#Permanently deletes a webhook endpoint. This action cannot be undone.
Parameters
Name
Type
Description
id
string
Required. The unique identifier of the webhook endpoint to delete.
Returns
Returns the deleted webhook endpoint object.
import payment from '@blocklet/payment-js';

async function deleteWebhookEndpoint(endpointId) {
  try {
    const endpoint = await payment.webhooks.del(endpointId);
    console.log(`Successfully deleted webhook endpoint ${endpoint.id}.`);
    return endpoint;
  } catch (error) {
    console.error(`Error deleting webhook endpoint ${endpointId}:`, error.message);
  }
}

deleteWebhookEndpoint('whep_123456789');Example Response
{
  "id": "whep_123456789",
  "livemode": false,
  "api_version": "2024-01-01",
  "url": "https://example.com/webhook-receiver",
  "description": "Updated endpoint description",
  "enabled_events": [
    "charge.succeeded",
    "customer.subscription.deleted"
  ],
  "metadata": {},
  "status": "disabled",
  "created_at": "2024-05-21T10:00:00.000Z",
  "created_via": "api",
  "updated_at": "2024-05-21T10:05:00.000Z"
}
After configuring your webhooks, you might want to manage payment refunds. Proceed to the Refunds API Reference to learn more.

Attribute	Type	Description
`id`	`string`	Unique identifier for the webhook endpoint.
`livemode`	`boolean`	`true` if the object exists in live mode, or `false` if it exists in test mode.
`api_version`	`string`	The API version used to render the event data sent to the endpoint.
`url`	`string`	The URL of the webhook endpoint.
`description`	`string`	An optional description of the webhook endpoint.
`enabled_events`	`string[]`	The list of event types that this endpoint is configured to receive. Examples include `'charge.succeeded'`, `'customer.subscription.created'`.
`metadata`	`object`	A set of key-value pairs that you can attach to an object. Useful for storing additional information.
`status`	`string`	The status of the webhook endpoint, can be either `'enabled'` or `'disabled'`.
`created_at`	`Date`	Timestamp of when the object was created.
`created_via`	`string`	How the endpoint was created, either `'api'`, `'dashboard'`, or `'portal'`.
`updated_at`	`Date`	Timestamp of the last update.

Name	Type	Description
`url`	`string`	Required. The URL where event notifications will be sent via POST request.
`enabled_events`	`string[]`	Required. An array of event type strings that you want to subscribe to.
`description`	`string`	An optional description for the endpoint.
`api_version`	`string`	The API version for the event data. Defaults to your account's default API version.
`metadata`	`object`	Optional key-value data to store with the endpoint.
`status`	`string`	The initial status of the endpoint. Can be `'enabled'` or `'disabled'`. Defaults to `'enabled'`.

Name	Type	Description
`id`	`string`	Required. The identifier of the endpoint to update.
`url`	`string`	The new URL for the endpoint.
`enabled_events`	`string[]`	The new list of event types to subscribe to. This will replace the existing list.
`description`	`string`	An updated description.
`status`	`string`	The new status, either `'enabled'` or `'disabled'`.
`metadata`	`object`	New metadata. This will replace the existing metadata.

Overview

Get Started

Core Concepts

Usage Guides

API Reference

TypeScript Support

Webhooks

The Webhook Endpoint Object#

Create a Webhook Endpoint#

Retrieve a Webhook Endpoint#

Update a Webhook Endpoint#

List all Webhook Endpoints#

Delete a Webhook Endpoint#

Subscription Items

Refunds

Name	Type	Description
`page`	`number`	The page number for pagination, starting from 1.
`pageSize`	`number`	The number of items to return per page. Defaults to 20.
`order`	`string	string[]`

Name	Type	Description
`count`	`number`	The total number of endpoints matching the query.
`list`	`object[]`	An array of webhook endpoint objects.