Webhooks
Update a webhook endpoint
Apply a partial update. Omitting a field leaves it unchanged.
Field behavior:
urlmust use HTTPS, the same rule as create.description: an empty string after trimming clears the label; a non-empty value updates it. Values longer than 200 characters are rejected.events, when present, replaces the entire subscription set. To add an event incrementally, read the currentevents, append, and send the full set back.activeturns delivery on or off without deleting the endpoint.
api_version is immutable. To change the envelope version, create a new
endpoint at the new version and delete the old one once you have verified
the cutover.
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
Path Parameters
id*string
Format
uuidRequest 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 PATCH "https://example.com/v1/webhooks/497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{}'{
"id": "0190a1b2-c3d4-e5f6-a7b8-c9d0e1f2a3b4",
"org_id": "0190a1b2-c3d4-e5f6-a7b8-c9d0e1f2a3b5",
"url": "https://hooks.example.com/y3labs/ops",
"events": [
"wallet.balance_low",
"wallet.balance_zero",
"subscription.past_due",
"subscription.canceled"
],
"active": true,
"api_version": "2026-04-01",
"created_at": "2026-04-26T12:00:00Z",
"updated_at": "2026-04-27T08:30:00Z",
"deleted_at": null
}{
"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": "NOT_FOUND",
"message": "not found",
"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"
}
}
}