Usage Guides

Webhooks

Webhooks enable your application to receive real-time notifications for events that occur within your PaymentKit account, such as a completed checkout or an updated subscription. Instead of polling the API for changes, you can configure a webhook endpoint, and PaymentKit will send an HTTP POST request with the event details to your specified URL.
This guide will walk you through setting up and managing webhook endpoints using the PaymentKit SDK. For a complete list of methods, see the Webhooks API Reference.
The Webhook Flow#When an event you've subscribed to occurs, PaymentKit sends a POST request to your server. Your server should then process this event to automate backend tasks like updating a database, sending confirmation emails, or provisioning services.
"Your Webhook Server""PaymentKit System""User Action""Your Webhook Server""PaymentKit System""User Action"Completes a checkoutGenerates 'checkout.session.completed' eventSends HTTP POST to your configured URLResponds with 2xx status to acknowledge receiptProcesses the event (e.g., fulfill order)

The Webhook Endpoint Object#A webhook endpoint object contains the configuration for receiving events. Here are its main attributes:
Attribute
Type
Description
id
string
The unique identifier for the webhook endpoint.
url
string
The URL where the webhook events will be sent.
enabled_events
string[]
The list of event types that this endpoint is subscribed to.
status
string
The current status of the endpoint, either "enabled" or "disabled".
description
string
An optional description for the endpoint.
api_version
string
The API version used to create the endpoint.
livemode
boolean
Indicates if the object was created in live mode (true) or test mode (false).
created_at
Date
The timestamp when the endpoint was created.
Create a Webhook Endpoint#To start receiving events, create a webhook endpoint and specify the events you want to monitor.
Parameters
Name
Type
Description
url
string
Required. The URL of your server that will receive the webhook POST requests.
enabled_events
string[]
Required. An array of event type strings to subscribe to. See the full list of available events below.
description
string
An optional description for easy identification.
Example
import payment from '@blocklet/payment-js';

async function setupWebhook() {
  try {
    const webhook = await payment.webhookEndpoints.create({
      url: 'https://example.com/webhook-handler',
      enabled_events: [
        'checkout.session.completed',
        'customer.subscription.created',
        'customer.subscription.deleted'
      ],
      description: 'Webhook for primary application events'
    });
    console.log('Webhook endpoint created:', webhook);
  } catch (error) {
    console.error('Error creating webhook endpoint:', error.message);
  }
}

setupWebhook();Example Response
{
  "id": "wh_1234567890abcdef",
  "livemode": false,
  "api_version": "1.0.0",
  "url": "https://example.com/webhook-handler",
  "description": "Webhook for primary application events",
  "enabled_events": [
    "checkout.session.completed",
    "customer.subscription.created",
    "customer.subscription.deleted"
  ],
  "metadata": {},
  "status": "enabled",
  "created_at": "2023-10-27T10:00:00.000Z",
  "created_via": "api",
  "updated_at": "2023-10-27T10:00:00.000Z"
}List Webhook Endpoints#Retrieve a paginated list of all your webhook endpoints.
Parameters
Name
Type
Description
page
number
The page number to retrieve. Defaults to 1.
pageSize
number
The number of endpoints to return per page. Defaults to 20.
order
string
The order to sort the results, e.g., "created_at:DESC".
Example
import payment from '@blocklet/payment-js';

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

listWebhooks();Example Response
{
  "count": 1,
  "list": [
    {
      "id": "wh_1234567890abcdef",
      "livemode": false,
      "api_version": "1.0.0",
      "url": "https://example.com/webhook-handler",
      "description": "Webhook for primary application events",
      "enabled_events": [
        "checkout.session.completed",
        "customer.subscription.created"
      ],
      "metadata": {},
      "status": "enabled",
      "created_at": "2023-10-27T10:00:00.000Z",
      "created_via": "api",
      "updated_at": "2023-10-27T10:00:00.000Z"
    }
  ]
}Update a Webhook Endpoint#Modify an existing webhook endpoint, such as changing its URL or the list of enabled events.
Parameters
Name
Type
Description
id
string
Required. The ID of the webhook endpoint to update.
data
object
Required. An object containing the fields to update.
Fields for data object
Name
Type
Description
url
string
A new URL for the endpoint.
enabled_events
string[]
A new list of event types. This will replace the existing list.
description
string
An updated description.
status
string
Set to "enabled" or "disabled".
Example
import payment from '@blocklet/payment-js';

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

updateWebhook('wh_1234567890abcdef');Delete a Webhook Endpoint#You can permanently delete a webhook endpoint if it's no longer needed.
Parameters
Name
Type
Description
id
string
Required. The ID of the webhook endpoint to delete.
Example
import payment from '@blocklet/payment-js';

async function deleteWebhook(id) {
  try {
    const deletedWebhook = await payment.webhookEndpoints.del(id);
    console.log(`Webhook ${deletedWebhook.id} has been deleted.`);
  } catch (error) {
    console.error('Error deleting webhook:', error.message);
  }
}

deleteWebhook('wh_1234567890abcdef');Available Event Types#You can subscribe to a wide range of events. Below are some of the most common categories and event types:
Checkout
checkout.session.completed
checkout.session.expired
checkout.session.nft_minted
Customer & Subscription
customer.created
customer.deleted
customer.updated
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
customer.subscription.paused
customer.subscription.resumed
customer.subscription.renewed
customer.subscription.renew_failed
Payments & Refunds
payment_intent.created
payment_intent.succeeded
payment_intent.payment_failed
refund.created
refund.succeeded
Credit Billing
customer.credit.insufficient
customer.credit_grant.granted
customer.credit_grant.low_balance
customer.credit_grant.depleted
This is not an exhaustive list. Refer to the EventType definition for all possible values.

Managing webhooks is crucial for building a responsive and automated payment system. You can now create endpoints to listen for important events and act on them in real-time. To learn more about handling payments, proceed to the Checkout Sessions guide.

Attribute	Type	Description
`id`	`string`	The unique identifier for the webhook endpoint.
`url`	`string`	The URL where the webhook events will be sent.
`enabled_events`	`string[]`	The list of event types that this endpoint is subscribed to.
`status`	`string`	The current status of the endpoint, either `"enabled"` or `"disabled"`.
`description`	`string`	An optional description for the endpoint.
`api_version`	`string`	The API version used to create the endpoint.
`livemode`	`boolean`	Indicates if the object was created in live mode (`true`) or test mode (`false`).
`created_at`	`Date`	The timestamp when the endpoint was created.

Name	Type	Description
`url`	`string`	Required. The URL of your server that will receive the webhook POST requests.
`enabled_events`	`string[]`	Required. An array of event type strings to subscribe to. See the full list of available events below.
`description`	`string`	An optional description for easy identification.

Name	Type	Description
`page`	`number`	The page number to retrieve. Defaults to `1`.
`pageSize`	`number`	The number of endpoints to return per page. Defaults to `20`.
`order`	`string`	The order to sort the results, e.g., `"created_at:DESC"`.

Name	Type	Description
`id`	`string`	Required. The ID of the webhook endpoint to update.
`data`	`object`	Required. An object containing the fields to update.

Name	Type	Description
`url`	`string`	A new URL for the endpoint.
`enabled_events`	`string[]`	A new list of event types. This will replace the existing list.
`description`	`string`	An updated description.
`status`	`string`	Set to `"enabled"` or `"disabled"`.

Overview

Get Started

Core Concepts

Usage Guides

API Reference

TypeScript Support

Webhooks

The Webhook Flow#

The Webhook Endpoint Object#

Create a Webhook Endpoint#

List Webhook Endpoints#

Update a Webhook Endpoint#

Delete a Webhook Endpoint#

Available Event Types#

Refunds

API Reference