Create Webhook

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 example

{
  "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: `ACTIVE` or `DISABLED`
`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 create and reset-secret responses
`created_at`	string	Creation time, ISO 8601
`updated_at`	string	Last update time, ISO 8601
`request_id`	string	Unique request identifier

The signing secret is returned only in the create and reset-secret responses. Store it securely; subsequent queries do not return it.

Error codes

HTTP status	Error code	Description
400	`11800016`	Parameter, subscription event, or URL validation failed
401	`InvalidApiKey`	Invalid API key provided

​Prerequisites

​Endpoint

​Request body

​Request example

​Response example

​Response fields

​Error codes

Prerequisites

Endpoint

Request body

Request example

Response example

Response fields

Error codes