> ## Documentation Index
> Fetch the complete documentation index at: https://hub.hcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a webhook

> Register a URL to receive signed event notifications.

Registers a [webhook](/computer-use-agents/webhooks/overview) 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`.

<Warning>
  The `secret` cannot be retrieved later. To replace it, use [Rotate](/computer-use-agents/webhooks/rotate).
</Warning>

***

## Request body

<ParamField body="url" type="string" required>
  Target URL for deliveries. 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`.
</ParamField>

<ParamField body="enabled_events" type="string[]" default={["*"]}>
  Event types delivered to this webhook. `"*"` subscribes to the `session.status_updated` firehose; granular `session.*` types are delivered only when listed explicitly. See the [event catalog](/computer-use-agents/webhooks/events) for supported types.
</ParamField>

<ParamField body="description" type="string">
  Optional label for the webhook (max 255 characters).
</ParamField>

***

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  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
  ```

  ```typescript TypeScript theme={null}
  import { HaiAgentsClient } from "hai-agents";

  const client = new HaiAgentsClient();

  const webhook = await client.webhooks.createWebhook({
    url: "https://example.com/hooks/h",
    enabledEvents: ["session.status_updated"],
    description: "Production listener",
  });
  console.log(webhook.secret); // shown only once; store it securely
  ```
</CodeGroup>

```json Response theme={null}
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "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`.                                              |