Create Webhook
Updated at:
Creates a Webhook endpoint that subscribes to named events and delivers them to a specified callback URL. The signing secret is returned only in this response. Each workspace can create at most 20 webhooks.
Prerequisites
Endpoint and authentication configured. For details, see Overview and authentication.
Endpoint
POST /webhook_endpoints
Request body
| Field | Required | Type | Description |
|---|---|---|---|
url | Yes | string | Callback URL; HTTP or HTTPS allowed, any port, domain or public IP accepted; private, loopback, link-local, and reserved addresses are rejected |
events | Yes | array<string> | Array of named event types to subscribe to; wildcard subscriptions are not supported |
description | No | string | Description, max 256 characters |
Request example
curl -X POST "$AGENTSTUDIO_URL/webhook_endpoints" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "Production session events",
"url": "https://example.com/managedagent/webhooks",
"events": [
"session.updated",
"session.status_idled",
"session.thread_terminated"
]
}'
Response
{
"id": "wep_01JXX7YQGPRPV1BZXA35QE7WDP",
"description": "Production session events",
"url": "https://example.com/managedagent/webhooks",
"events": [
"session.updated",
"session.status_idled",
"session.thread_terminated"
],
"status": "ACTIVE",
"disabled_reason": null,
"consecutive_fail": 0,
"last_success_at": null,
"last_failure_at": null,
"signing_secret": "whsec_xxx",
"created_at": "2026-08-06T10:00:00Z",
"updated_at": "2026-08-06T10:00:00Z",
"request_id": "8e1d16e4"
}
Response fields
| Field | Type | Description |
|---|---|---|
id | string | Webhook ID, format wep_<ULID> |
description | string | null | Description |
url | string | Callback URL |
events | array<string> | Subscribed named event types |
status | string | Webhook status |
disabled_reason | string | null | Disable reason; null when not disabled |
consecutive_fail | integer | Current consecutive failure count; 0 for new webhooks |
last_success_at | string | null | Last successful delivery time; null for new webhooks |
last_failure_at | string | null | Last failed delivery time; null for new webhooks |
signing_secret | string | Signing secret, format whsec_ + standard Base64 text. Returned only in successful create and reset responses |
created_at | string | Creation time, ISO 8601 |
updated_at | string | Last update time, ISO 8601 |
request_id | string | Unique request identifier |
Error codes
| HTTP status | Error code | Description |
|---|---|---|
| 400 | 11800016 | invalid webhook request |
| 401 | InvalidApiKey | Invalid API-key provided. |
Is this page helpful?