Skip to main content
POST
/
api
/
v2
/
webhooks
Create a webhook
curl --request POST \
  --url https://agp.eu.hcompany.ai/api/v2/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "enabled_events": [
    "<string>"
  ],
  "description": "<string>"
}
'
Registers a webhook for your organization. The response includes the signing secret. This is the only time it is returned, so store it securely. Returns 201 with the created webhook object plus its secret.
The secret cannot be retrieved later. To rotate it, delete the webhook and create a new one.

​
Request body

​
url
string
required
Target URL for deliveries. Must be https:// and publicly reachable; deliveries to private or internal hosts are skipped.
​
enabled_events
string[]
default:["*"]
Event types delivered to this webhook. "*" subscribes to all current and future types. Supported types: session.status_updated.
​
description
string
Optional label for the webhook (max 255 characters).

​
Examples

curl -X POST https://agp.eu.hcompany.ai/api/v2/webhooks \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/h",
    "enabled_events": ["session.status_updated"],
    "description": "Production listener"
  }'
Response
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "url": "https://example.com/hooks/h",
  "enabled_events": ["session.status_updated"],
  "description": "Production listener",
  "disabled": false,
  "created_at": "2026-06-11T15:04:05Z",
  "updated_at": "2026-06-11T15:04:05Z",
  "secret": "whsec_k3TQyhq2mPv8WdJ4cN7xLbR9sF1aZ6uE0gYoHiC5jXw"
}

​
Errors

StatusCause
400Organization webhook limit reached (10).
422Body failed validation: non-https URL, empty or unknown enabled_events.