Create a webhook

Create a webhook that gets signed notifications when sessions change status.

POST /api/v2/webhooks

Python

from hai_agents import Client

client = Client()

webhook = client.webhooks.create_webhook(
    url="https://example.com/hooks/h",
    enabled_events=["session.status_updated"],
    description="Production listener",
)
print(webhook.secret)  # shown only once; store it securely

201

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "url": "https://example.com/hooks/h",
  "enabled_events": ["session.status_updated"],
  "description": "Production listener",
  "disabled": false,
  "last_delivery_status": null,
  "last_delivery_error": null,
  "last_delivery_at": null,
  "last_success_at": null,
  "consecutive_failures": 0,
  "created_at": "2026-06-11T15:04:05Z",
  "updated_at": "2026-06-11T15:04:05Z",
  "secret": "whsec_k3TQyhq2mPv8WdJ4cN7xLbR9sF1aZ6uE0gYoHiC5jXw"
}

Behavior

Each event in enabled_events arrives as a signed POST, with the payload and signature check in Webhooks.

The secret is returned once and cannot be retrieved later. To replace it, use Rotate secret.

Request body

url · string · required

Target URL for deliveries, up to 2048 characters. Must be https:// and publicly reachable: the platform sends a HEAD request at creation time and rejects the webhook if the endpoint cannot be reached. Any HTTP status counts as reachable. Your endpoint does not need to accept HEAD.

enabled_events · string[] · default: ["*"]

Event types delivered to this webhook. "*" subscribes to the session.status_updated firehose. Granular session.* types are delivered only when named explicitly (Event types).

description · string

Label for the webhook, up to 255 characters.

Response

201 with the created webhook object plus its secret.

Python

from hai_agents import Client

client = Client()

webhook = client.webhooks.create_webhook(
    url="https://example.com/hooks/h",
    enabled_events=["session.status_updated"],
    description="Production listener",
)
print(webhook.secret)  # shown only once; store it securely

201

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "url": "https://example.com/hooks/h",
  "enabled_events": ["session.status_updated"],
  "description": "Production listener",
  "disabled": false,
  "last_delivery_status": null,
  "last_delivery_error": null,
  "last_delivery_at": null,
  "last_success_at": null,
  "consecutive_failures": 0,
  "created_at": "2026-06-11T15:04:05Z",
  "updated_at": "2026-06-11T15:04:05Z",
  "secret": "whsec_k3TQyhq2mPv8WdJ4cN7xLbR9sF1aZ6uE0gYoHiC5jXw"
}

Errors

Status	Cause
400	Organization webhook limit reached (10), URL does not resolve to a public address, or the endpoint could not be reached.
422	Body failed validation: non-https URL, empty or unknown enabled_events.