Skip to main content

​
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. Navigate to Webhooks in the sidebar
  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: 
{
  "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: 
Status: 200 OK
Response Time: 145ms
Response Body: {"received": true}
Failure: 
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
  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

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

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

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

Verifying Signatures

Secure your webhook endpoint

Webhook Logs

View test results in logs

Creating Webhooks

Configure webhook settings

Webhooks Overview

Learn about webhooks

Statistics

  • Level: beginner
  • Time: 5 minutes

Tags

webhooks, testing, debugging, development