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

# Create Webhook

> Register a new webhook endpoint

## Overview

Create a new webhook to receive HTTP notifications when events occur. The response includes a signing secret that is **only shown once** -- save it immediately.

**Auth:** Requires JWT token (`Authorization: Bearer <token>`).

## Body Parameters

<ParamField body="url" type="string" required>
  The HTTPS URL to receive webhook deliveries. Must start with `https://`.
</ParamField>

<ParamField body="events" type="string[]" required>
  Event types to subscribe to. At least one is required.

  Valid values:

  * `tool.execution.completed`
  * `tool.execution.failed`
  * `workflow.completed`
  * `workflow.failed`
  * `agent.spend.limit_approaching`
</ParamField>

<ParamField body="description" type="string">
  Optional description for your reference (e.g. "Production monitoring")
</ParamField>

## Response

<ResponseField name="id" type="string">
  Webhook UUID
</ResponseField>

<ResponseField name="url" type="string">
  The registered URL
</ResponseField>

<ResponseField name="events" type="string[]">
  Subscribed event types
</ResponseField>

<ResponseField name="is_active" type="boolean">
  Always `true` on creation
</ResponseField>

<ResponseField name="description" type="string">
  Optional description
</ResponseField>

<ResponseField name="secret" type="string">
  The signing secret (format: `whsec_...`). **Only returned on creation.** Use this to verify webhook signatures via HMAC-SHA256.
</ResponseField>

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.danubeai.com/v1/webhooks" \
    -H "Authorization: Bearer YOUR_JWT_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com/webhooks/danube",
      "events": ["tool.execution.completed", "tool.execution.failed"],
      "description": "Production monitoring"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "url": "https://example.com/webhooks/danube",
    "events": ["tool.execution.completed", "tool.execution.failed"],
    "is_active": true,
    "description": "Production monitoring",
    "secret": "whsec_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6"
  }
  ```
</ResponseExample>

<Warning>
  The `secret` field is only returned when the webhook is created. Store it securely -- you will need it to verify webhook signatures. See the [Webhooks guide](/webhooks) for verification examples.
</Warning>