Creating Webhooks

This guide walks you through creating a webhook to receive real-time notifications when API requests pass through your routes.

Prerequisites

Before creating a webhook, you’ll need:

A KnoxCall account with at least one route
An endpoint URL that can receive HTTP POST requests
(Optional) Authentication credentials for your endpoint

Step 1: Navigate to Webhooks

Open the KnoxCall admin dashboard
Click Automation in the sidebar, then select Webhooks
Click + Create Webhook

Step 2: Basic Configuration

Name and Description

Give your webhook a descriptive name:

Name: Slack Error Notifications
Description: Send Slack alerts when payment routes return 5xx errors

Best practices:

Use descriptive names that explain the purpose
Include the destination in the name (e.g., “Slack”, “Zapier”, “Datadog”)
Add context in the description

Webhook URL

Enter the endpoint URL where KnoxCall will send webhook events:

URL: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXX

Supported protocols:

https:// (recommended)
http:// (for development only)

Use HTTPS in production. HTTP endpoints may expose sensitive data in transit.

HTTP Method

Choose the HTTP method for webhook requests:

Method	Use Case
POST (default)	Most webhook endpoints
PUT	Some REST APIs that expect PUT
PATCH	Partial updates
GET	Query-based webhooks (payload in query params)

Step 3: Event Types

Select which events should trigger this webhook:

Request Lifecycle Events

request.received

Triggers when a request first arrives at KnoxCall, before forwarding to the backend.Use cases:

Real-time request monitoring
Request logging
Pre-flight webhooks

request.success

Triggers when the backend returns a 2xx response.Use cases:

Success tracking
Post-transaction webhooks
Analytics

request.redirect

Triggers when the backend returns a 3xx response.Use cases:

Redirect monitoring
SEO tracking

request.client_error

Triggers when the backend returns a 4xx response.Use cases:

Invalid request tracking
Authentication failure alerts
Rate limit notifications

request.server_error

Triggers when the backend returns a 5xx response.Use cases:

Error alerting (Slack, PagerDuty)
Incident management
Backend health monitoring

request.timeout

Triggers when the request times out before receiving a response.Use cases:

Timeout monitoring
Performance alerts
SLA tracking

request.error

Triggers on any non-2xx response (4xx, 5xx, or timeout).Use cases:

General error monitoring
Catch-all error handler

request.completed

Triggers on every completed request, regardless of status.Use cases:

Comprehensive logging
Analytics
Audit trails

Example selection for error alerting:

Selected Events:
✓ request.server_error
✓ request.timeout

Step 4: Route Filtering (Optional)

By default, webhooks trigger for all routes in your tenant. To limit to specific routes:

Toggle on Route Filter
Select the routes you want to monitor

Example:

Route Filter:
✓ payment-api
✓ checkout-service
✗ internal-admin (excluded)

Leave route filter empty to trigger for all routes. This is useful for logging or analytics webhooks.

Step 5: Authentication

Configure how KnoxCall authenticates with your webhook endpoint:

No Authentication

Auth Type: None

Use for endpoints that don’t require authentication (e.g., some Slack webhooks).

Bearer Token

Auth Type: Bearer
Token: your-secret-token-here

KnoxCall sends:

Authorization: Bearer your-secret-token-here

Basic Authentication

Auth Type: Basic
Username: webhook_user
Password: secret_password

KnoxCall sends:

Authorization: Basic d2ViaG9va191c2VyOnNlY3JldF9wYXNzd29yZA==

Custom Header

Auth Type: Header
Header Name: X-API-Key
Header Value: your-api-key-here

KnoxCall sends:

X-API-Key: your-api-key-here

HMAC Signature (Always Included)

Regardless of auth type, every webhook includes an HMAC signature:

X-Webhook-Signature: sha256=abc123def456...

Use this to verify the webhook came from KnoxCall.

Step 6: Payload Options

Control what data is included in the webhook payload:

Include Request Body

Default: Yes When enabled, includes the original request body:

{
  "data": {
    "request": {
      "body": { "amount": 1000, "currency": "usd" }
    }
  }
}

Disable for:

Large payloads that would slow down delivery
Sensitive data you don’t want in logs

Include Response Body

Default: Yes When enabled, includes the backend response body:

{
  "data": {
    "response": {
      "body": { "id": "ch_123", "status": "succeeded" }
    }
  }
}

Disable for:

Large response payloads
Sensitive response data

Include Headers

Default: No When enabled, includes request and response headers:

{
  "data": {
    "request": {
      "headers": { "content-type": "application/json", "user-agent": "..." }
    },
    "response": {
      "headers": { "content-type": "application/json" }
    }
  }
}

Sensitive headers (Authorization, API keys, cookies) are automatically redacted when included.

Include Status Code

Default: Yes When enabled, includes the HTTP status code:

{
  "data": {
    "response": {
      "status": 200
    }
  }
}

Step 7: Retry Configuration

Configure how KnoxCall handles failed deliveries:

Retry on Failure

Default: Yes When enabled, KnoxCall retries failed webhook deliveries. Failure conditions:

Connection timeout
HTTP 5xx response from your endpoint
Network errors

HTTP 4xx responses are not retried, as they typically indicate a client error.

Max Retries

Default: 3 (Range: 0-5) Number of retry attempts after the initial failure. Retry schedule:

Attempt	Delay
1 (initial)	Immediate
2	1 second
3	2 seconds
4	4 seconds
5	8 seconds

Timeout

Default: 30 seconds (Range: 1-60) How long to wait for a response from your webhook endpoint before timing out. Recommendations:

Slack/Zapier: 10-15 seconds
Custom endpoints: 30 seconds
Slow backends: Up to 60 seconds

Step 8: Custom Headers (Optional)

Add additional HTTP headers to webhook requests:

{
  "X-Custom-Header": "my-value",
  "X-Environment": "production",
  "X-Source": "knoxcall"
}

Use cases:

Identify the source of webhooks
Pass environment information
Custom routing in your endpoint

Step 9: Enable and Save

Toggle Enabled to ON (default)
Click Create Webhook

Your webhook is now active and will trigger on the configured events!

Testing Your Webhook

After creating, test your webhook:

Click the Test button on the webhook detail page
KnoxCall sends a test payload with event: webhook.test
View the result:
- Success: HTTP 2xx response
- Failure: Error message and response details

Test payload example:

{
  "event": "webhook.test",
  "timestamp": "2025-01-15T10:30:45.123Z",
  "test": true,
  "data": {
    "route_id": "00000000-0000-0000-0000-000000000000",
    "route_name": "Test Route",
    "request": { "method": "POST", "path": "/api/test" },
    "response": { "status": 200, "latency_ms": 42 }
  }
}

Example Configurations

Slack Error Alerts

Name: Slack Payment Errors
URL: https://hooks.slack.com/services/...
Method: POST
Events: request.server_error, request.timeout
Auth: None
Payload:
  Include Request Body: No
  Include Response Body: Yes
  Include Headers: No
Retry: Yes (3 attempts)
Timeout: 10 seconds

Analytics Logging

Name: Analytics Full Logging
URL: https://analytics.yourcompany.com/ingest
Method: POST
Events: request.completed
Route Filter: (all routes)
Auth: Bearer token
Payload:
  Include Request Body: Yes
  Include Response Body: Yes
  Include Headers: Yes
Retry: Yes (5 attempts)
Timeout: 30 seconds

Zapier Integration

Name: Zapier Payment Success
URL: https://hooks.zapier.com/hooks/catch/123456/abcdef
Method: POST
Events: request.success
Route Filter: payment-api only
Auth: None
Payload:
  Include Request Body: Yes
  Include Response Body: Yes
  Include Headers: No
Retry: Yes (3 attempts)
Timeout: 15 seconds

Managing Your Signing Secret

Each webhook has a unique signing secret for HMAC verification:

View Secret

Open webhook detail page
Click Reveal Secret
Copy the secret for use in your verification code

Regenerate Secret

Open webhook detail page
Click Regenerate Secret
Copy the new secret immediately
Update your verification code

Regenerating invalidates the old secret immediately. Make sure to update your verification code before regenerating.

Next Steps

Testing Webhooks

Verify your webhook configuration

Webhook Logs

Monitor webhook deliveries

Verifying Signatures

Secure your webhook endpoint

Webhooks Overview

Learn about webhook concepts

Statistics

Level: beginner
Time: 10 minutes

​Creating Webhooks

​Prerequisites

​Step 1: Navigate to Webhooks

​Step 2: Basic Configuration

​Name and Description

​Webhook URL

​HTTP Method

​Step 3: Event Types

​Request Lifecycle Events

​Step 4: Route Filtering (Optional)

​Step 5: Authentication

​No Authentication

​Bearer Token

​Basic Authentication

​Custom Header

​HMAC Signature (Always Included)

​Step 6: Payload Options

​Include Request Body

​Include Response Body

​Include Headers

​Include Status Code

​Step 7: Retry Configuration

​Retry on Failure

​Max Retries

​Timeout

​Step 8: Custom Headers (Optional)

​Step 9: Enable and Save

​Testing Your Webhook

​Example Configurations

​Slack Error Alerts

​Analytics Logging

​Zapier Integration

​Managing Your Signing Secret

​View Secret

​Regenerate Secret

​Next Steps

Testing Webhooks

Webhook Logs

Verifying Signatures

Webhooks Overview

Statistics

Tags

Creating Webhooks

Prerequisites

Step 1: Navigate to Webhooks

Step 2: Basic Configuration

Name and Description

Webhook URL

HTTP Method

Step 3: Event Types

Request Lifecycle Events

Step 4: Route Filtering (Optional)

Step 5: Authentication

No Authentication

Bearer Token

Basic Authentication

Custom Header

HMAC Signature (Always Included)

Step 6: Payload Options

Include Request Body

Include Response Body

Include Headers

Include Status Code

Step 7: Retry Configuration

Retry on Failure

Max Retries

Timeout

Step 8: Custom Headers (Optional)

Step 9: Enable and Save

Testing Your Webhook

Example Configurations

Slack Error Alerts

Analytics Logging

Zapier Integration

Managing Your Signing Secret

View Secret

Regenerate Secret

Next Steps