Skip to main content

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

POST /v1/webhooks
Creates a new webhook. The secret_key for verifying webhook signatures is returned only once in the response.

​
Request Body

FieldTypeRequiredDescription
namestringYesDisplay name for the webhook
urlstringYesThe URL to deliver webhook payloads to
event_typesstring[]YesEvents 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
descriptionstringNoDescription
methodstringNoHTTP method for delivery (defaults to POST)
auth_typestringNoAuthentication type: none, basic, bearer, hmac, header (defaults to none)
auth_configobjectNoAuth credentials (depends on auth_type)
request_headersobjectNoCustom headers to include in deliveries
route_filterstring[]NoOnly trigger for events on these route IDs (array of UUIDs)
include_request_bodybooleanNoInclude the original request body in the payload (defaults to true)
include_response_bodybooleanNoInclude the upstream response body (defaults to false)
include_headersbooleanNoInclude request/response headers (defaults to false)
timeout_secondsintegerNoDelivery timeout in seconds (defaults to 30)
retry_on_failurebooleanNoRetry failed deliveries (defaults to true)
max_retriesintegerNoMaximum retry attempts (defaults to 3)
enabledbooleanNoEnable immediately (defaults to true)
hmac_key_iduuidNoCrypto Keys transit key ID to use for HMAC signing (stage 2.5; replaces the secret_key-based default signing)
hmac_formatstringNoSignature format when using hmac_key_id: legacy, stripe, github, slack, aws-sns, custom
hmac_header_namestringNoCustom 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": "whsec_a1b2c3d4e5f6..."
  },
  "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.
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"
  }'

​
Errors

StatusTypeDescription
400validation_errorMissing required fields or empty event_types array