Create Webhook
POST /v1/webhooks
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. |
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
{
"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" }
}
The
secret_key is returned only at creation time. Store it securely — you’ll need it to verify webhook signatures. See the Verifying Signatures guide.import { KnoxCall } from "@knoxcall/sdk";
const client = new KnoxCall(); // credentials from `knoxcall login` or KNOXCALL_CLIENT_ID / KNOXCALL_CLIENT_SECRET
const webhook = await client.webhooks.create({
name: "Error Notifications",
url: "https://hooks.slack.com/services/T00/B00/xxx",
event_types: ["request.error", "request.timeout"],
description: "Notify Slack on 5xx errors"
});
console.log(`Store webhook secret: ${webhook.secret_key}`);
from knoxcall import KnoxCall
client = KnoxCall() # credentials from `knoxcall login` or KNOXCALL_CLIENT_ID / KNOXCALL_CLIENT_SECRET
webhook = client.webhooks.create(
name="Error Notifications",
url="https://hooks.slack.com/services/T00/B00/xxx",
event_types=["request.error", "request.timeout"],
description="Notify Slack on 5xx errors"
)
print(f"Store webhook secret: {webhook['secret_key']}")
# Mint a 1-hour OAuth token (client_credentials) — see /api-reference/authentication
TOKEN=$(curl -s -X POST https://api.knoxcall.com/oauth/token \
-u "$KNOXCALL_CLIENT_ID:$KNOXCALL_CLIENT_SECRET" \
-d "grant_type=client_credentials" | jq -r .access_token)
curl -X POST https://api.knoxcall.com/v1/webhooks \
-H "Authorization: Bearer $TOKEN" \
-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"
}'
Errors
| Status | Type | Description |
|---|---|---|
| 400 | validation_error | Missing required fields or empty event_types array |