cURL
curl --request POST 'https://api.integrateledger.com/v1/webhook-endpoints' \
-H "Authorization: Bearer $LEDGER_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"url":"https://example.com/webhooks/ledger","enabledEvents":["subscription.created","balance.low"]}'import ledger from "integrateledger";
const client = new ledger({ apiKey: process.env.LEDGER_API_KEY ?? "" });
await client.createWebhookEndpoint({ url: "https://example.com/webhooks/ledger", enabledEvents: ["subscription.created", "balance.low"] });import os
from integrateledger import ledger
client = ledger(api_key=os.environ["LEDGER_API_KEY"])
client.create_webhook_endpoint(url="https://example.com/webhooks/ledger", enabled_events=["subscription.created", "balance.low"]){
"object": "webhook_endpoint",
"id": "<string>",
"url": "<string>",
"description": "<string>",
"enabledEvents": [
"<string>"
],
"apiVersion": "<string>",
"status": "enabled",
"disabledReason": "failing",
"disabledAt": "<string>",
"failingSince": "<string>",
"livemode": true,
"environment": "sandbox",
"createdAt": "<string>",
"updatedAt": "<string>",
"secret": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "payload_too_large"
}{
"error": "rate_limited"
}Webhooks
Create a webhook endpoint
Register a URL for Ledger to send signed events to, in the environment your API key selects.
POST
/
v1
/
webhook-endpoints
cURL
curl --request POST 'https://api.integrateledger.com/v1/webhook-endpoints' \
-H "Authorization: Bearer $LEDGER_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"url":"https://example.com/webhooks/ledger","enabledEvents":["subscription.created","balance.low"]}'import ledger from "integrateledger";
const client = new ledger({ apiKey: process.env.LEDGER_API_KEY ?? "" });
await client.createWebhookEndpoint({ url: "https://example.com/webhooks/ledger", enabledEvents: ["subscription.created", "balance.low"] });import os
from integrateledger import ledger
client = ledger(api_key=os.environ["LEDGER_API_KEY"])
client.create_webhook_endpoint(url="https://example.com/webhooks/ledger", enabled_events=["subscription.created", "balance.low"]){
"object": "webhook_endpoint",
"id": "<string>",
"url": "<string>",
"description": "<string>",
"enabledEvents": [
"<string>"
],
"apiVersion": "<string>",
"status": "enabled",
"disabledReason": "failing",
"disabledAt": "<string>",
"failingSince": "<string>",
"livemode": true,
"environment": "sandbox",
"createdAt": "<string>",
"updatedAt": "<string>",
"secret": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "payload_too_large"
}{
"error": "rate_limited"
}Ledger sends the events in
enabledEvents to url, signed with the endpoint’s secret. Use ["*"] for every event, including ones added later. The event reference lists each type.
The response carries the signing secret (whsec_…) once. Store it, then verify each request with it. To replace it, rotate the secret in Settings › Webhooks.
- URL: Live endpoints must be public
https://URLs. Private, loopback and internal hosts are refused. - Limit: 16 endpoints per environment; another returns
409 endpoint_limit_reached. - Errors: an unknown event type is
400 invalid_request; a URL Ledger can’t send to is400 https_required,private_address,credentials_in_urlorinvalid_url.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Where Ledger sends events. Live and production endpoints must be public https:// URLs.
Required string length:
1 - 2048Example:
"https://example.com/webhooks/ledger"
Required array length:
1 - 50 elementsAn event type, or * for every event.
Available options:
*, customer.created, customer.deleted, subscription.created, subscription.updated, subscription.canceled, invoice.paid, credits.granted, balance.low, balance.depleted, checkout.completed, checkout.expired Maximum string length:
200Response
Endpoint created, with its signing secret
Available options:
webhook_endpoint Available options:
enabled, disabled Available options:
failing, manual, null Available options:
sandbox, live The signing secret (whsec_…). Returned only here; store it to verify the Ledger-Signature header.