> ## 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.
# Testing Webhooks
> Learn how to test your webhook configuration before going live. Use the built-in test feature and verify your endpoint receives data correctly.
# Testing Webhooks
Before relying on webhooks in production, test them to ensure your endpoint receives and processes data correctly.
## Built-in Test Feature
KnoxCall provides a one-click test feature for every webhook:
### How to Test
1. Click **Automation** in the sidebar, then select **Webhooks**
2. Click on your webhook
3. Click the **Test** button
4. View the results
### What Happens
When you click Test, KnoxCall:
1. Sends a test payload to your endpoint
2. Includes all configured headers and authentication
3. Signs the payload with your webhook secret
4. Records the response (or error)
5. Shows you the result
### Test Payload
The test payload includes a special `test: true` flag:
```json theme={"dark"}
{
"event": "webhook.test",
"timestamp": "2025-01-15T10:30:45.123Z",
"webhook_id": "wh_abc123",
"webhook_name": "My Webhook",
"test": true,
"data": {
"route_id": "00000000-0000-0000-0000-000000000000",
"route_name": "Test Route",
"request": {
"method": "POST",
"path": "/api/test",
"headers": { "content-type": "application/json" },
"body": { "example": "data" }
},
"response": {
"status": 200,
"headers": { "content-type": "application/json" },
"body": { "success": true },
"latency_ms": 42
}
}
}
```
### Test Results
**Success:**
```text theme={"dark"}
Status: 200 OK
Response Time: 145ms
Response Body: {"received": true}
```
**Failure:**
```text theme={"dark"}
Status: Failed
Error: Connection timeout after 30000ms
```
## Testing Locally
To test webhooks with a local development server:
### Using ngrok
1. Install ngrok: `npm install -g ngrok`
2. Start your local server: `node server.js` (port 3000)
3. Create a tunnel: `ngrok http 3000`
4. Copy the HTTPS URL: `https://abc123.ngrok.io`
5. Use this URL in your webhook configuration
### Using webhook.site
For quick testing without running a server:
1. Go to [webhook.site](https://webhook.site)
2. Copy your unique URL
3. Use it as your webhook endpoint
4. Watch requests arrive in real-time
## Verifying Test Requests
On your endpoint, verify that test requests:
### 1. Arrive with Correct Headers
```http theme={"dark"}
Content-Type: application/json
X-Webhook-Signature: sha256=abc123...
X-Webhook-ID: wh_abc123
X-Webhook-Event: webhook.test
User-Agent: KnoxCall-Webhook/1.0
```
### 2. Include Valid Signature
```javascript theme={"dark"}
const crypto = require('crypto');
app.post('/webhook', (req, res) => {
const signature = req.headers['x-webhook-signature'];
const payload = JSON.stringify(req.body);
const expected = 'sha256=' + crypto
.createHmac('sha256', process.env.WEBHOOK_SECRET)
.update(payload)
.digest('hex');
if (signature === expected) {
console.log('Signature valid!');
} else {
console.log('Signature invalid!');
}
res.status(200).json({ received: true });
});
```
### 3. Contain Expected Data
```javascript theme={"dark"}
app.post('/webhook', (req, res) => {
const { event, test, data } = req.body;
if (test) {
console.log('This is a test webhook');
}
console.log('Event:', event);
console.log('Route:', data.route_name);
console.log('Status:', data.response.status);
res.status(200).json({ received: true });
});
```
## Testing Different Scenarios
### Test Success Events
1. Create a route pointing to a working API
2. Make a successful request through the route
3. Verify your webhook receives `request.success` event
### Test Error Events
1. Create a route pointing to a non-existent URL
2. Make a request through the route
3. Verify your webhook receives `request.server_error` event
### Test Timeout Events
1. Create a route with a short timeout (5 seconds)
2. Point it to a slow API
3. Verify your webhook receives `request.timeout` event
## Troubleshooting Test Failures
### "Connection refused"
**Cause:** Your endpoint isn't running or isn't accessible.
**Fix:**
* Verify your server is running
* Check the URL is correct (including port)
* Ensure firewall allows incoming connections
### "Connection timeout"
**Cause:** Your endpoint is too slow or unreachable.
**Fix:**
* Check network connectivity
* Ensure endpoint responds within timeout (default: 30s)
* Reduce processing time in your handler
### "SSL certificate error"
**Cause:** Invalid or self-signed certificate.
**Fix:**
* Use a valid SSL certificate
* For testing, use HTTP (not recommended for production)
* Use a service like Let's Encrypt for free certificates
### "401 Unauthorized"
**Cause:** Authentication credentials are incorrect.
**Fix:**
* Verify Bearer token is correct
* Check Basic auth username/password
* Ensure custom header name/value are correct
### "Signature mismatch"
**Cause:** You're verifying with the wrong secret.
**Fix:**
* Copy the secret from KnoxCall webhook settings
* Ensure you're using the raw JSON body (not parsed)
* Check for encoding issues
## Best Practices
### 1. Always Test Before Production
Run the built-in test before enabling webhooks for real traffic.
### 2. Check Webhook Logs
After testing, review the webhook logs to see:
* What was sent
* What response was received
* Any error messages
### 3. Test All Event Types
If you subscribe to multiple events, test scenarios that trigger each one.
### 4. Verify Signature Handling
Ensure your endpoint correctly validates signatures before processing data.
### 5. Test Retry Behavior
Intentionally return an error to verify retries work as expected.
## Next Steps
Secure your webhook endpoint
View test results in logs
Configure webhook settings
Learn about webhooks
***
* **Level**: beginner
* **Time**: 5 minutes
`webhooks`, `testing`, `debugging`, `development`