Webhooks
Create a webhook endpoint
Subscribe a URL to one or more organization-level events.
The endpoint's signing secret is returned in the secret field exactly
once (base64-encoded). There is no endpoint that reads it back; rotate
the endpoint to mint a new one.
Validation:
urlmust use HTTPS. A bad scheme returns422 VALIDATION_FAILEDwithdetails.url.eventsmust be 1 to 50 entries, each a known event type. Duplicates and unknown names return422 VALIDATION_FAILEDindetails.events.descriptionmust be 200 characters or fewer; longer values return422 VALIDATION_FAILED.api_versionmust be a supported version; unknown or deprecated versions return422 VALIDATION_FAILED.
Your organization can hold up to 50 active endpoints. Exceeding the cap
returns 409 LIMIT_EXCEEDED.
Requires the webhooks:write scope.
AuthorizationBearer <token>
Authenticate by sending your API key as a bearer token:
Authorization: Bearer am_live_.... Every request is automatically
scoped to the organization that owns the key and to the scopes granted
to that key.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/webhooks" \ -H "Content-Type: application/json" \ -d '{ "url": "https://hooks.example.com/y3labs/ops", "events": [ "wallet.balance_low" ] }'{
"id": "0190a1b2-c3d4-e5f6-a7b8-c9d0e1f2a3b4",
"org_id": "0190a1b2-c3d4-e5f6-a7b8-c9d0e1f2a3b5",
"url": "https://hooks.example.com/y3labs/ops",
"events": [
"wallet.balance_low"
],
"active": true,
"api_version": "2026-04-01",
"created_at": "2026-04-26T12:00:00Z",
"updated_at": "2026-04-26T12:00:00Z",
"deleted_at": null,
"secret": "qhhFHQ59wgBQOfACvc/V7wYS2GpIiSh+ZBPyGWfA8MM=",
"secret_displayed_once": true
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "authentication failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "missing required scope",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "LIMIT_EXCEEDED",
"message": "webhook endpoint limit reached (max 50)",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "VALIDATION_FAILED",
"message": "validation failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM",
"details": {
"to": "must be E.164",
"body": "must be 1..1600 chars"
}
}
}