> ## 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.
# Creating Webhooks
> Step-by-step guide to creating and configuring webhooks in KnoxCall. Set up event subscriptions, authentication, and payload options.
# 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 **Automation** in the sidebar, then select **Webhooks**
3. Click **+ Create Webhook**
## Step 2: Basic Configuration
### Name and Description
Give your webhook a descriptive name:
```text theme={"dark"}
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:
```text theme={"dark"}
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
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:**
```text theme={"dark"}
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:**
```text theme={"dark"}
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
```text theme={"dark"}
Auth Type: None
```
Use for endpoints that don't require authentication (e.g., some Slack webhooks).
### Bearer Token
```text theme={"dark"}
Auth Type: Bearer
Token: your-secret-token-here
```
KnoxCall sends:
```http theme={"dark"}
Authorization: Bearer your-secret-token-here
```
### Basic Authentication
```text theme={"dark"}
Auth Type: Basic
Username: webhook_user
Password: secret_password
```
KnoxCall sends:
```http theme={"dark"}
Authorization: Basic d2ViaG9va191c2VyOnNlY3JldF9wYXNzd29yZA==
```
### Custom Header
```text theme={"dark"}
Auth Type: Header
Header Name: X-API-Key
Header Value: your-api-key-here
```
KnoxCall sends:
```http theme={"dark"}
X-API-Key: your-api-key-here
```
### HMAC Signature (Always Included)
Regardless of auth type, every webhook includes an HMAC signature:
```http theme={"dark"}
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:
```json theme={"dark"}
{
"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:
```json theme={"dark"}
{
"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:
```json theme={"dark"}
{
"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:
```json theme={"dark"}
{
"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:
```json theme={"dark"}
{
"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:**
```json theme={"dark"}
{
"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
```yaml theme={"dark"}
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
```yaml theme={"dark"}
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
```yaml theme={"dark"}
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
Verify your webhook configuration
Monitor webhook deliveries
Secure your webhook endpoint
Learn about webhook concepts
***
* **Level**: beginner
* **Time**: 10 minutes
`webhooks`, `configuration`, `setup`, `events`, `authentication`