Skip to main content
POST
/
api
/
webhooks
/
subscriptions
Create subscription
curl --request POST \
  --url https://api.example.com/api/webhooks/subscriptions \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "events": [
    "<string>"
  ],
  "label": "<string>"
}
'
{
  "id": "1c84203c-b4e3-40de-83a9-51bc0d9c991f",
  "url": "https://hooks.example.com/teel",
  "events": ["payout.created", "payout.status.updated"],
  "status": "active",
  "secretPrefix": "whsec_Pdt_BP",
  "secret": "whsec_Pdt_BP3ft-nIDl86430kZrGEy8qd7zB4pCUmeU1GVB0",
  "label": "Production receiver",
  "lastSuccessAt": null,
  "lastFailureAt": null,
  "createdAt": "2026-05-27T09:30:00Z",
  "updatedAt": "2026-05-27T09:30:00Z"
}
Register a delivery URL.
The response includes secret (a whsec_… signing secret) once. Store it on receipt — only the secretPrefix is retrievable later.
Scope webhooks:write · rate-limited

​
Headers

​
Authorization
string
required
API key.

​
Request body

​
url
string
required
Endpoint URL. Must be https://. Rejected with 400 if it’s a private IP, loopback, or metadata host.
​
events
string[]
required
Non-empty list of event types. Allowed: payout.created, payout.status.updated.
​
label
string
Optional human-readable label for the dashboard. Never sent to your endpoint.

​
Response

​
id
string
Subscription UUID.
​
secret
string
The signing secret in plaintext. Returned only on create — store it immediately.
​
secretPrefix
string
First few characters of the secret for partner-side identification on subsequent reads.
​
status
string
Always active on a new subscription.
The other fields (url, events, label, lastSuccessAt, lastFailureAt, createdAt, updatedAt) match the shape on List subscriptions. 
{
  "id": "1c84203c-b4e3-40de-83a9-51bc0d9c991f",
  "url": "https://hooks.example.com/teel",
  "events": ["payout.created", "payout.status.updated"],
  "status": "active",
  "secretPrefix": "whsec_Pdt_BP",
  "secret": "whsec_Pdt_BP3ft-nIDl86430kZrGEy8qd7zB4pCUmeU1GVB0",
  "label": "Production receiver",
  "lastSuccessAt": null,
  "lastFailureAt": null,
  "createdAt": "2026-05-27T09:30:00Z",
  "updatedAt": "2026-05-27T09:30:00Z"
}

​
Errors

StatusMeaning
400Invalid URL (not https, missing host, private IP, metadata host) or unknown event type.
409You’ve reached the per-account limit (25). Delete or pause an existing one first.