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

# Create Webhook

> Create a new webhook to receive real-time event notifications

## Create Webhook

```text theme={"dark"}
POST /v1/webhooks
```

Creates a new webhook. The `secret_key` for verifying webhook signatures is returned **only once** in the response.

### Request Body

| Field                   | Type      | Required | Description                                                                                                                                                                                                                                                                                          |
| ----------------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                  | string    | Yes      | Display name for the webhook                                                                                                                                                                                                                                                                         |
| `url`                   | string    | Yes      | The URL to deliver webhook payloads to                                                                                                                                                                                                                                                               |
| `event_types`           | string\[] | Yes      | Events to subscribe to (non-empty array). Supported: `request.received`, `request.success`, `request.redirect`, `request.client_error`, `request.server_error`, `request.timeout`, `request.error`, `request.completed`, `audit.event`. See [List Event Types](/api-reference/webhooks/event-types). |
| `description`           | string    | No       | Description                                                                                                                                                                                                                                                                                          |
| `method`                | string    | No       | HTTP method for delivery (defaults to `POST`)                                                                                                                                                                                                                                                        |
| `auth_type`             | string    | No       | Authentication type: `none`, `basic`, `bearer`, `hmac`, `header` (defaults to `none`)                                                                                                                                                                                                                |
| `auth_config`           | object    | No       | Auth credentials (depends on `auth_type`)                                                                                                                                                                                                                                                            |
| `request_headers`       | object    | No       | Custom headers to include in deliveries                                                                                                                                                                                                                                                              |
| `route_filter`          | string\[] | No       | Only trigger for events on these route IDs (array of UUIDs)                                                                                                                                                                                                                                          |
| `include_request_body`  | boolean   | No       | Include the original request body in the payload (defaults to `true`)                                                                                                                                                                                                                                |
| `include_response_body` | boolean   | No       | Include the upstream response body (defaults to `false`)                                                                                                                                                                                                                                             |
| `include_headers`       | boolean   | No       | Include request/response headers (defaults to `false`)                                                                                                                                                                                                                                               |
| `timeout_seconds`       | integer   | No       | Delivery timeout in seconds (defaults to `30`)                                                                                                                                                                                                                                                       |
| `retry_on_failure`      | boolean   | No       | Retry failed deliveries (defaults to `true`)                                                                                                                                                                                                                                                         |
| `max_retries`           | integer   | No       | Maximum retry attempts (defaults to `3`)                                                                                                                                                                                                                                                             |
| `enabled`               | boolean   | No       | Enable immediately (defaults to `true`)                                                                                                                                                                                                                                                              |
| `hmac_key_id`           | uuid      | No       | Crypto Keys transit key ID to use for HMAC signing (stage 2.5; replaces the `secret_key`-based default signing)                                                                                                                                                                                      |
| `hmac_format`           | string    | No       | Signature format when using `hmac_key_id`: `legacy`, `stripe`, `github`, `slack`, `aws-sns`, `custom`                                                                                                                                                                                                |
| `hmac_header_name`      | string    | No       | Custom header name when `hmac_format` is `custom`                                                                                                                                                                                                                                                    |

### Response

```json theme={"dark"}
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Error Notifications",
    "description": "Notify Slack on 5xx errors",
    "url": "https://hooks.slack.com/services/T00/B00/xxx",
    "method": "POST",
    "event_types": ["request.error", "request.timeout"],
    "auth_type": "none",
    "enabled": true,
    "hmac_key_id": null,
    "hmac_format": null,
    "hmac_header_name": null,
    "created_at": "2026-01-20T10:00:00.000Z",
    "secret_key": "3f9c1a4e8b2d6075e1c93af0d4b78652a9f1e0c3b6d8275a4e1f93c0b7a6d2e7"
  },
  "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}
```

<Warning>
  The `secret_key` is returned **only at creation time**. Store it securely -- you'll need it to verify webhook signatures. See the [Verifying Signatures](/webhooks/verifying-signatures) guide.
</Warning>

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST https://api.knoxcall.com/v1/webhooks \
    -H "Authorization: Bearer tk_live_abc123..." \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Error Notifications",
      "url": "https://hooks.slack.com/services/T00/B00/xxx",
      "event_types": ["request.error", "request.timeout"],
      "description": "Notify Slack on 5xx errors"
    }'
  ```

  ```python Python theme={"dark"}
  import requests

  resp = requests.post(
      "https://api.knoxcall.com/v1/webhooks",
      headers={
          "Authorization": "Bearer tk_live_abc123...",
          "Content-Type": "application/json"
      },
      json={
          "name": "Error Notifications",
          "url": "https://hooks.slack.com/services/T00/B00/xxx",
          "event_types": ["request.error", "request.timeout"],
          "description": "Notify Slack on 5xx errors"
      }
  )
  webhook = resp.json()["data"]
  print(f"Store webhook secret: {webhook['secret_key']}")
  ```

  ```javascript Node.js theme={"dark"}
  const resp = await fetch("https://api.knoxcall.com/v1/webhooks", {
    method: "POST",
    headers: {
      Authorization: "Bearer tk_live_abc123...",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name: "Error Notifications",
      url: "https://hooks.slack.com/services/T00/B00/xxx",
      event_types: ["request.error", "request.timeout"],
      description: "Notify Slack on 5xx errors"
    })
  });
  const { data: webhook } = await resp.json();
  console.log(`Store webhook secret: ${webhook.secret_key}`);
  ```
</CodeGroup>

### Errors

| Status | Type               | Description                                          |
| ------ | ------------------ | ---------------------------------------------------- |
| 400    | `validation_error` | Missing required fields or empty `event_types` array |