Webhooks

Webhooks let you receive real-time HTTP callbacks when events occur on your routes — such as successful requests, errors, rate limit hits, and more. KnoxCall signs every webhook delivery so you can verify authenticity.

List Webhooks

GET /v1/webhooks

Returns a paginated list of all webhooks in your tenant.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`per_page`	integer	`20`	Items per page (max 100)
`sort`	string	`created_at`	Sort by: `created_at`, `name`, or `enabled`
`order`	string	`desc`	Sort direction: `asc` or `desc`

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,
      "last_triggered_at": "2026-03-10T14:22:01.000Z",
      "trigger_count": 142,
      "success_count": 140,
      "failure_count": 2,
      "created_at": "2026-01-20T10:00:00.000Z"
    }
  ],
  "meta": {
    "total": 4,
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

curl https://api.knoxcall.com/v1/webhooks \
  -H "Authorization: Bearer tk_live_abc123..."

Get Webhook

GET /v1/webhooks/:id

Returns the full configuration for a single webhook, including delivery statistics.

Path Parameters

Parameter	Type	Description
`id`	uuid	The webhook ID

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",
    "request_headers": null,
    "route_filter": null,
    "include_request_body": true,
    "include_response_body": false,
    "include_headers": false,
    "timeout_seconds": 30,
    "retry_on_failure": true,
    "max_retries": 3,
    "enabled": true,
    "last_triggered_at": "2026-03-10T14:22:01.000Z",
    "last_success_at": "2026-03-10T14:22:01.000Z",
    "last_failure_at": "2026-02-28T08:15:00.000Z",
    "trigger_count": 142,
    "success_count": 140,
    "failure_count": 2,
    "created_at": "2026-01-20T10:00:00.000Z"
  },
  "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}

Errors

Status	Type	Description
404	`not_found`	Webhook not found

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

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)
`description`	string	No	Description
`method`	string	No	HTTP method for delivery (defaults to `POST`)
`auth_type`	string	No	Authentication type: `none`, `basic`, `bearer`, `hmac` (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 a specific route ID
`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`)

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,
    "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

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

Update Webhook

PATCH /v1/webhooks/:id

Updates one or more fields on an existing webhook.

Path Parameters

Parameter	Type	Description
`id`	uuid	The webhook ID

Request Body

All fields are optional. Only provided fields will be updated.

Field	Type	Description
`name`	string	Display name
`description`	string	Description
`url`	string	Delivery URL
`method`	string	HTTP method
`event_types`	string[]	Subscribed event types
`auth_type`	string	Authentication type
`auth_config`	object	Authentication credentials
`request_headers`	object	Custom delivery headers
`route_filter`	string	Route ID filter
`include_request_body`	boolean	Include request body
`include_response_body`	boolean	Include response body
`include_headers`	boolean	Include headers
`timeout_seconds`	integer	Delivery timeout
`retry_on_failure`	boolean	Retry on failure
`max_retries`	integer	Max retry attempts
`enabled`	boolean	Enable or disable

Response

Returns the updated webhook object (without secret_key).

Errors

Status	Type	Description
400	`validation_error`	No valid fields provided
404	`not_found`	Webhook not found

Delete Webhook

DELETE /v1/webhooks/:id

Permanently deletes a webhook and all of its delivery logs.

Path Parameters

Parameter	Type	Description
`id`	uuid	The webhook ID

Response

{
  "data": { "deleted": true },
  "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}

Errors

Status	Type	Description
404	`not_found`	Webhook not found

Get Webhook Logs

GET /v1/webhooks/:id/logs

Returns paginated delivery logs for a specific webhook, showing every delivery attempt with status and timing.

Path Parameters

Parameter	Type	Description
`id`	uuid	The webhook ID

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`per_page`	integer	`20`	Items per page (max 100)

Response

{
  "data": [
    {
      "id": "log-uuid",
      "request_method": "POST",
      "request_path": "/services/T00/B00/xxx",
      "request_ip": "203.0.113.1",
      "response_status": 200,
      "response_time_ms": 342,
      "executed_at": "2026-03-10T14:22:01.000Z",
      "success": true,
      "error_message": null
    }
  ],
  "meta": {
    "total": 142,
    "page": 1,
    "per_page": 20,
    "total_pages": 8,
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Errors

Status	Type	Description
404	`not_found`	Webhook not found

API Overview

Endpoints

List Webhooks

Query Parameters

Response

Get Webhook

Path Parameters

Response

Errors

Create Webhook

Request Body

Response

Errors

Update Webhook

Path Parameters

Request Body

Response

Errors

Delete Webhook

Path Parameters

Response

Errors

Get Webhook Logs

Path Parameters

Query Parameters

Response

Errors

API Overview

Endpoints

​List Webhooks

​Query Parameters

​Response

​Get Webhook

​Path Parameters

​Response

​Errors

​Create Webhook

​Request Body

​Response

​Errors

​Update Webhook

​Path Parameters

​Request Body

​Response

​Errors

​Delete Webhook

​Path Parameters

​Response

​Errors

​Get Webhook Logs

​Path Parameters

​Query Parameters

​Response

​Errors

List Webhooks

Query Parameters

Response

Get Webhook

Path Parameters

Response

Errors

Create Webhook

Request Body

Response

Errors

Update Webhook

Path Parameters

Request Body

Response

Errors

Delete Webhook

Path Parameters

Response

Errors

Get Webhook Logs

Path Parameters

Query Parameters

Response

Errors