Skip to main content
POST
/
webhooks
Create a webhook endpoint
curl --request POST \
  --url https://api.billing.io/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://example.com/webhooks/billing",
  "events": [],
  "description": "<string>"
}
'
{
  "webhook_id": "<string>",
  "url": "<string>",
  "events": [],
  "secret": "<string>",
  "description": "<string>",
  "created_at": "2023-11-07T05:31:56Z"
}
Register a webhook endpoint to receive event notifications. The signing secret is only returned once at creation. 
curl -X POST https://api.billing.io/v1/webhooks \
  -H "Authorization: Bearer $BILLING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/billing",
    "events": ["checkout.completed", "checkout.expired"],
    "description": "Production webhook"
  }'
Response
{
  "webhook_id": "we_a1b2c3d4e5f6a7b8c9d0e1f2",
  "url": "https://your-app.com/webhooks/billing",
  "events": ["checkout.completed", "checkout.expired"],
  "secret": "whsec_a1b2c3d4e5f6a7b8c9d0e1f2",
  "status": "active",
  "created_at": "2025-01-15T12:00:00Z"
}

Authorizations

​
Authorization
string
header
required

Use your secret API key as a Bearer token. Keys are prefixed: sk_live_ (production) or sk_test_ (sandbox).

Body

application/json
​
url
string<uri>
required

HTTPS endpoint to receive events

Example:

"https://example.com/webhooks/billing"

​
events
enum<string>[]
required

Event types to subscribe to

Minimum array length: 1
Available options:
checkout.created,
checkout.payment_detected,
checkout.confirming,
checkout.completed,
checkout.expired,
checkout.failed
​
description
string

Human-readable label

Maximum string length: 256

Response

Webhook endpoint created

​
webhook_id
string

Unique identifier (prefixed we_)

​
url
string<uri>
​
events
enum<string>[]
Available options:
checkout.created,
checkout.payment_detected,
checkout.confirming,
checkout.completed,
checkout.expired,
checkout.failed
​
secret
string

HMAC signing secret (prefixed whsec_). Only returned on creation — store it securely.

​
description
string | null
​
status
enum<string>
Available options:
active,
disabled
​
created_at
string<date-time>