Skip to main content

​
Webhooks Overview

Webhooks let you send real-time notifications to external services whenever requests pass through your KnoxCall routes. Use them to trigger workflows, update databases, send alerts, or integrate with third-party services.

​
What Are Webhooks?

Webhooks are outbound HTTP requests that KnoxCall sends to your specified endpoint when certain events occur. How it works: 
Client Request → KnoxCall Route → Backend API
                      ↓
              Webhook Triggered
                      ↓
         Your Webhook Endpoint (Slack, Zapier, custom server, etc.)
Example use case: 
Route: payment-api
Event: request.server_error (5xx)
Webhook URL: https://hooks.slack.com/services/...
Result: Slack notification when payment API fails

​
Event Types

KnoxCall supports 8 event types that follow a Stripe-like naming convention:
Event TypeTriggers WhenExample Use Case
request.receivedRequest arrives at KnoxCallLogging, real-time dashboards
request.success2xx response receivedAnalytics, success tracking
request.redirect3xx response receivedRedirect monitoring
request.client_error4xx response receivedInvalid request tracking
request.server_error5xx response receivedError alerting
request.timeoutRequest times outTimeout monitoring
request.errorAny non-2xx responseGeneral error handling
request.completedAny response completedComprehensive logging
Combine event types: You can subscribe a single webhook to multiple event types. For example, subscribe to both request.success and request.server_error to track all outcomes.

​
Webhook Payload

When an event occurs, KnoxCall sends a JSON payload to your endpoint: 
{
  "event": "request.success",
  "timestamp": "2025-01-15T10:30:45.123Z",
  "webhook_id": "wh_abc123",
  "webhook_name": "Slack Notifications",
  "data": {
    "route_id": "route_xyz789",
    "route_name": "payment-api",
    "environment": "production",
    "request": {
      "method": "POST",
      "path": "/v1/charges",
      "ip": "52.123.45.67",
      "headers": { "content-type": "application/json" },
      "body": { "amount": 1000, "currency": "usd" }
    },
    "response": {
      "status": 200,
      "headers": { "content-type": "application/json" },
      "body": { "id": "ch_abc123", "status": "succeeded" },
      "latency_ms": 342
    }
  }
}

​
Payload Configuration

Control what’s included in your webhook payload:
OptionDefaultDescription
Include Request BodyYesInclude the original request body
Include Response BodyYesInclude the backend response body
Include HeadersNoInclude request/response headers
Include Status CodeYesInclude HTTP status code
Sensitive data: When including headers, sensitive headers like Authorization, X-API-Key, and Cookie are automatically redacted for security.

​
Authentication Methods

Secure your webhook endpoints with multiple authentication options:

​
Bearer Token

Authorization: Bearer your-secret-token

​
Basic Auth

Authorization: Basic base64(username:password)

​
Custom Header

X-Custom-Auth: your-secret-value

​
HMAC Signature

Every webhook includes an HMAC-SHA256 signature for verification: 
X-Webhook-Signature: sha256=abc123...
Verify the signature on your server: 
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return `sha256=${expectedSignature}` === signature;
}

​
Headers Sent

KnoxCall includes these headers with every webhook request:
HeaderDescription
Content-TypeAlways application/json
X-Webhook-SignatureHMAC-SHA256 signature for verification
X-Webhook-IDUnique identifier for the webhook configuration
X-Webhook-EventEvent type (e.g., request.success)
User-AgentKnoxCall-Webhook/1.0
Plus any custom headers you configure.

​
Route Filtering

Limit webhooks to specific routes: All routes (default): 
Route Filter: (empty)
→ Triggers for all routes in your tenant
Specific routes: 
Route Filter: ["route_abc123", "route_def456"]
→ Only triggers for these two routes
Use case: Create separate webhooks for different integrations:
  • payment-webhook: Only payment-related routes → Slack #payments
  • auth-webhook: Only authentication routes → Security monitoring tool

​
Retry Logic

When a webhook delivery fails, KnoxCall can automatically retry: Configuration:
  • Retry on Failure: Enable/disable retries
  • Max Retries: 0-5 attempts (default: 3)
Backoff schedule: 
Attempt 1: Immediate
Attempt 2: 1 second delay
Attempt 3: 2 seconds delay
Attempt 4: 4 seconds delay
Attempt 5: 8 seconds delay
Success criteria: HTTP 2xx response
Webhooks are dispatched asynchronously (fire-and-forget). They don’t block or slow down the proxied request.

​
Webhook Logs

Track all webhook executions in the webhook logs: What’s logged:
  • Execution timestamp
  • Event type
  • HTTP method and URL
  • Sent headers and body
  • Response status and body
  • Response time (ms)
  • Success/failure status
  • Error messages (if failed)
  • Retry count
  • Linked request ID
Filter logs by:
  • Webhook ID
  • Success/failure status
  • Event type
  • Date range
  • Request ID (to correlate with API logs)

​
Common Use Cases

​
1. Error Alerting (Slack)

Event: request.server_error
URL: https://hooks.slack.com/services/...
Include: Status code, route name, error message

​
2. Analytics/Logging

Event: request.completed
URL: https://your-analytics.com/ingest
Include: All data (full request/response)

​
3. Workflow Automation (Zapier)

Event: request.success
URL: https://hooks.zapier.com/hooks/catch/...
Include: Request body, response body

​
4. Security Monitoring

Event: request.client_error (401, 403)
URL: https://your-security-tool.com/api
Include: Request headers, IP address

​
5. Real-time Dashboards

Event: request.received
URL: wss://your-dashboard.com/ws
Include: Route name, timestamp

​
Performance Considerations

  • Non-blocking: Webhooks are dispatched asynchronously
  • Parallel dispatch: Multiple webhooks for the same event run in parallel
  • Timeout: Configurable timeout (1-60 seconds, default: 30)
  • No impact on latency: Webhook failures don’t affect the proxied request

​
Next Steps

Creating Webhooks

Step-by-step webhook setup guide

Testing Webhooks

How to test your webhook configuration

Webhook Logs

Viewing and debugging webhook executions

API Logs

Correlate webhooks with API requests

Statistics

  • Level: intermediate
  • Time: 8 minutes

Tags

webhooks, notifications, events, integrations, slack, zapier