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

FieldRequiredTypeDescription
urlYesstringCallback URL; HTTP or HTTPS allowed, any port, domain or public IP accepted; private, loopback, link-local, and reserved addresses are rejected
eventsYesarray<string>Array of named event types to subscribe to; wildcard subscriptions are not supported
descriptionNostringDescription, 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

FieldTypeDescription
idstringWebhook ID, format wep_<ULID>
descriptionstring | nullDescription
urlstringCallback URL
eventsarray<string>Subscribed named event types
statusstringWebhook status
disabled_reasonstring | nullDisable reason; null when not disabled
consecutive_failintegerCurrent consecutive failure count; 0 for new webhooks
last_success_atstring | nullLast successful delivery time; null for new webhooks
last_failure_atstring | nullLast failed delivery time; null for new webhooks
signing_secretstringSigning secret, format whsec_ + standard Base64 text. Returned only in successful create and reset responses
created_atstringCreation time, ISO 8601
updated_atstringLast update time, ISO 8601
request_idstringUnique request identifier

Error codes

HTTP statusError codeDescription
40011800016invalid webhook request
401InvalidApiKeyInvalid API-key provided.