API reference
Webhook Endpoints
You can configure webhook endpoints via the API to be notified about events that happen in your Stripe account or connected accounts. Most users configure webhooks from the dashboard, which provides a user interface for registering and testing your webhook endpoints. Related guide: Setting up webhooks
Create a webhook endpoint
POST/v1/webhook_endpoints
A webhook endpoint must have a url and a list of enabled_events. You may optionally specify the Boolean connect parameter. If set to true, then a Connect webhook endpoint that notifies the specified url about events from all connected accounts is created; otherwise an account webhook endpoint that notifies the specified url only about events from your account is created. You can also create webhook endpoints in the webhooks settings section of the Dashboard.
Body parameters
enabled_eventsarray of stringsRequiredThe list of events to enable for this endpoint. You may specify
['*']to enable all events, except those that require explicit selection.urlstringRequiredThe URL of the webhook endpoint.
api_versionstringEvents sent to this endpoint will be generated with this Stripe Version instead of your account's default Stripe Version.
Possible values2026-03-25.dahlia2026-04-22.dahlia2026-05-27.dahlia2026-06-24.dahlia2026-07-29.dahlia2026-08-26.dahlia
connectbooleanWhether this endpoint should receive events from connected accounts (
true), or from your account (false). Defaults tofalse.descriptionstringAn optional description of what the webhook is used for.
expandarray of stringsSpecifies which fields in the response should be expanded.
metadataobjectSet of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to
metadata.
Returns
The webhook_endpoint object.
curl https://api.knoxapi.com/v1/webhook_endpoints \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
-d "enabled_events[]=charge.failed" \
-d url=https://example.com/my/webhook/endpointconst Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const webhookEndpoint = await stripe.webhookEndpoints.create({
enabled_events: ['charge.failed'],
url: 'https://example.com/my/webhook/endpoint',
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
webhook_endpoint = client.v1.webhook_endpoints.create(params={
"enabled_events": ["charge.failed"],
"url": "https://example.com/my/webhook/endpoint",
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
webhook_endpoint = Stripe::WebhookEndpoint.create({
enabled_events: ['charge.failed'],
url: 'https://example.com/my/webhook/endpoint',
}){
"api_version": null,
"application": null,
"created": 1234567890,
"description": "This is my webhook, I like it a lot",
"enabled_events": [
"charge.failed",
"charge.succeeded"
],
"id": "we_1Pgc6yB7WZ01zgkWzAudq4eU",
"livemode": false,
"metadata": {},
"object": "webhook_endpoint",
"status": "enabled",
"url": "https://example.com/my/webhook/endpoint"
}List all webhook endpoints
GET/v1/webhook_endpoints
Returns a list of your webhook endpoints.
Query parameters
ending_beforestringA cursor for use in pagination.
ending_beforeis an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting withobj_bar, your subsequent call can includeending_before=obj_barin order to fetch the previous page of the list.expandarray of stringsSpecifies which fields in the response should be expanded.
limitintegerA limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
starting_afterstringA cursor for use in pagination.
starting_afteris an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending withobj_foo, your subsequent call can includestarting_after=obj_fooin order to fetch the next page of the list.
Returns
A list of webhook_endpoint objects.
curl -G https://api.knoxapi.com/v1/webhook_endpoints \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
--data-urlencode limit=3const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const page = await stripe.webhookEndpoints.list({
limit: 3,
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
page = client.v1.webhook_endpoints.list(params={
"limit": 3,
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
page = Stripe::WebhookEndpoint.list({
limit: 3,
}){
"object": "list",
"url": "/v1/webhook_endpoints",
"has_more": false,
"data": [
{
"api_version": null,
"application": null,
"created": 1234567890,
"description": "This is my webhook, I like it a lot",
"enabled_events": [
"charge.failed",
"charge.succeeded"
],
"id": "we_1Pgc6yB7WZ01zgkWzAudq4eU",
"livemode": false,
"metadata": {},
"object": "webhook_endpoint",
"status": "enabled",
"url": "https://example.com/my/webhook/endpoint"
}
]
}Update a webhook endpoint
POST/v1/webhook_endpoints/{webhook_endpoint}
Updates the webhook endpoint. You may edit the url, the list of enabled_events, and the status of your endpoint.
Path parameters
webhook_endpointstringRequired
Body parameters
descriptionstringAn optional description of what the webhook is used for.
disabledbooleanDisable the webhook endpoint if set to true.
enabled_eventsarray of stringsThe list of events to enable for this endpoint. You may specify
['*']to enable all events, except those that require explicit selection.expandarray of stringsSpecifies which fields in the response should be expanded.
metadataobjectSet of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to
metadata.urlstringThe URL of the webhook endpoint.
Returns
The webhook_endpoint object.
curl https://api.knoxapi.com/v1/webhook_endpoints/we_1Pgc6yB7WZ01zgkWzAudq4eU \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
-d "metadata[order_id]=6735"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const webhookEndpoint = await stripe.webhookEndpoints.update('we_1Pgc6yB7WZ01zgkWzAudq4eU', {
metadata: {
order_id: '6735',
},
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
webhook_endpoint = client.v1.webhook_endpoints.update("we_1Pgc6yB7WZ01zgkWzAudq4eU", params={
"metadata": {
"order_id": "6735",
},
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
webhook_endpoint = Stripe::WebhookEndpoint.update('we_1Pgc6yB7WZ01zgkWzAudq4eU', {
metadata: {
order_id: '6735',
},
}){
"api_version": null,
"application": null,
"created": 1234567890,
"description": "This is my webhook, I like it a lot",
"enabled_events": [
"charge.failed",
"charge.succeeded"
],
"id": "we_1Pgc6yB7WZ01zgkWzAudq4eU",
"livemode": false,
"metadata": {},
"object": "webhook_endpoint",
"status": "enabled",
"url": "https://example.com/my/webhook/endpoint"
}Retrieve a webhook endpoint
GET/v1/webhook_endpoints/{webhook_endpoint}
Retrieves the webhook endpoint with the given ID.
Path parameters
webhook_endpointstringRequired
Query parameters
expandarray of stringsSpecifies which fields in the response should be expanded.
Returns
The webhook_endpoint object.
curl https://api.knoxapi.com/v1/webhook_endpoints/we_1Pgc6yB7WZ01zgkWzAudq4eU \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const webhookEndpoint = await stripe.webhookEndpoints.retrieve('we_1Pgc6yB7WZ01zgkWzAudq4eU');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
webhook_endpoint = client.v1.webhook_endpoints.retrieve("we_1Pgc6yB7WZ01zgkWzAudq4eU")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
webhook_endpoint = Stripe::WebhookEndpoint.retrieve('we_1Pgc6yB7WZ01zgkWzAudq4eU'){
"api_version": null,
"application": null,
"created": 1234567890,
"description": "This is my webhook, I like it a lot",
"enabled_events": [
"charge.failed",
"charge.succeeded"
],
"id": "we_1Pgc6yB7WZ01zgkWzAudq4eU",
"livemode": false,
"metadata": {},
"object": "webhook_endpoint",
"status": "enabled",
"url": "https://example.com/my/webhook/endpoint"
}Delete a webhook endpoint
DELETE/v1/webhook_endpoints/{webhook_endpoint}
You can also delete webhook endpoints via the webhook endpoint management page of the Stripe dashboard.
Path parameters
webhook_endpointstringRequired
Returns
The deleted_webhook_endpoint object.
curl -X DELETE https://api.knoxapi.com/v1/webhook_endpoints/we_1Pgc6yB7WZ01zgkWzAudq4eU \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const deletedWebhookEndpoint = await stripe.webhookEndpoints.del('we_1Pgc6yB7WZ01zgkWzAudq4eU');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
deleted_webhook_endpoint = client.v1.webhook_endpoints.delete("we_1Pgc6yB7WZ01zgkWzAudq4eU")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
deleted_webhook_endpoint = Stripe::WebhookEndpoint.delete('we_1Pgc6yB7WZ01zgkWzAudq4eU'){
"deleted": true,
"id": "we_1Pgc6yB7WZ01zgkWzAudq4eU",
"object": "webhook_endpoint"
}Operations and schemas come from the pinned Stripe OpenAPI specification (MIT); response examples from its fixtures. Nested object definitions and enums are in the complete specification.