Skip to main content

​
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:
  1. A KnoxCall account with at least one route
  2. An endpoint URL that can receive HTTP POST requests
  3. (Optional) Authentication credentials for your endpoint

​
Step 1: Navigate to Webhooks

  1. Open the KnoxCall admin dashboard
  2. Click Webhooks in the sidebar
  3. 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:
MethodUse Case
POST (default)Most webhook endpoints
PUTSome REST APIs that expect PUT
PATCHPartial updates
GETQuery-based webhooks (payload in query params)

​
Step 3: Event Types

Select which events should trigger this webhook:

​
Request Lifecycle Events

Triggers when a request first arrives at KnoxCall, before forwarding to the backend.Use cases:
  • Real-time request monitoring
  • Request logging
  • Pre-flight webhooks
Triggers when the backend returns a 2xx response.Use cases:
  • Success tracking
  • Post-transaction webhooks
  • Analytics
Triggers when the backend returns a 3xx response.Use cases:
  • Redirect monitoring
  • SEO tracking
Triggers when the backend returns a 4xx response.Use cases:
  • Invalid request tracking
  • Authentication failure alerts
  • Rate limit notifications
Triggers when the backend returns a 5xx response.Use cases:
  • Error alerting (Slack, PagerDuty)
  • Incident management
  • Backend health monitoring
Triggers when the request times out before receiving a response.Use cases:
  • Timeout monitoring
  • Performance alerts
  • SLA tracking
Triggers on any non-2xx response (4xx, 5xx, or timeout).Use cases:
  • General error monitoring
  • Catch-all error handler
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:
  1. Toggle on Route Filter
  2. 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:
AttemptDelay
1 (initial)Immediate
21 second
32 seconds
44 seconds
58 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

  1. Toggle Enabled to ON (default)
  2. Click Create Webhook
Your webhook is now active and will trigger on the configured events!

​
Testing Your Webhook

After creating, test your webhook:
  1. Click the Test button on the webhook detail page
  2. KnoxCall sends a test payload with event: webhook.test
  3. 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

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

​
Regenerate Secret

  1. Open webhook detail page
  2. Click Regenerate Secret
  3. Copy the new secret immediately
  4. 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

Tags

webhooks, configuration, setup, events, authentication