Skip to main content
Each subscription registers a URL that Teel POSTs signed events to. See the Webhooks guide for the delivery format, retry behavior, and verifier samples.

​
Account limits

LimitValue
Subscriptions per account25
Maximum payload size (JSON envelope)256 KB
URL schemehttps:// only
Loopback, RFC1918 private, link-local, and known cloud metadata host/IP ranges are rejected at create time and at delivery time (DNS is re-resolved before every POST).

​
List subscriptions

​
Authorization
string
required
Bearer token from Auth0
GET /api/webhooks/subscriptions

[
  {
    "id": "1c84203c-b4e3-40de-83a9-51bc0d9c991f",
    "user_id": "4d9e5f15-33bd-4b52-970d-88ad31dfe3ce",
    "url": "https://hooks.example.com/teel",
    "events": ["payout.created", "payout.status.updated"],
    "status": "active",
    "secret_prefix": "whsec_Pdt_BP",
    "label": "Production receiver",
    "created_at": "2026-05-27T09:30:00Z",
    "updated_at": "2026-05-27T09:30:00Z",
    "last_success_at": "2026-05-27T09:31:02Z",
    "last_failure_at": null
  }
]

​
Create subscription

​
Authorization
string
required
Bearer token from Auth0
​
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.
POST /api/webhooks/subscriptions
The response includes a one-shot secret field — your whsec_… signing secret. Copy it immediately. Subsequent reads of the subscription only return the secret_prefix; we cannot retrieve the plaintext later. 
{
  "id": "1c84203c-b4e3-40de-83a9-51bc0d9c991f",
  "user_id": "4d9e5f15-33bd-4b52-970d-88ad31dfe3ce",
  "url": "https://hooks.example.com/teel",
  "events": ["payout.created", "payout.status.updated"],
  "status": "active",
  "secret_prefix": "whsec_Pdt_BP",
  "secret": "whsec_Pdt_BP3ft-nIDl86430kZrGEy8qd7zB4pCUmeU1GVB0",
  "label": "Production receiver",
  "created_at": "2026-05-27T09:30:00Z",
  "updated_at": "2026-05-27T09:30:00Z",
  "last_success_at": null,
  "last_failure_at": null
}
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.

​
Get subscription

​
Authorization
string
required
Bearer token from Auth0
​
id
string
required
Subscription UUID
GET /api/webhooks/subscriptions/{id}
Returns the same shape as List but for a single row. Returns 404 if the id isn’t yours.

​
Update subscription

​
Authorization
string
required
Bearer token from Auth0
​
id
string
required
Subscription UUID
​
url
string
New endpoint URL. Same validation rules as create.
​
events
string[]
New event allow-list. Replaces existing.
​
status
string
active or paused. disabled is reserved for ops-side use and not user-settable.
​
label
string
New label.
PATCH /api/webhooks/subscriptions/{id}
All fields are optional — any field you omit stays unchanged. Returns the updated subscription. Pausing a subscription stops new deliveries from being enqueued; in-flight retries continue.

​
Delete subscription

​
Authorization
string
required
Bearer token from Auth0
​
id
string
required
Subscription UUID
DELETE /api/webhooks/subscriptions/{id}
Removes the subscription and all of its pending / historical deliveries (cascade). Returns {"deleted": true} on success.

​
Rotate signing secret

​
Authorization
string
required
Bearer token from Auth0
​
id
string
required
Subscription UUID
POST /api/webhooks/subscriptions/{id}/rotate-secret
Mints a new whsec_… secret and returns it once (same envelope as Create). The previous secret is invalidated immediately — there is no overlap window. If you need overlap, pause the subscription first, rotate, deploy your verifier with the new secret, and unpause.