Test Webhook Endpoints Before Going Live

Verify your webhook integration works before going live. Test endpoints locally, simulate events, and validate payloads. What you’ll learn: Local testing with ngrok, API test endpoint, payload validation, and debugging techniques.

Testing Methods

Method	Best For
Dashboard Test	Quick validation
webhook.site	Inspecting payloads without server
ngrok	Full integration testing with local server

API Test Endpoint

Send test webhooks programmatically:

const response = await fetch('https://blackbox.dasha.ai/api/v1/webhooks/test', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    webHook: {
      url: 'https://your-server.com/webhook',
      headers: { 'Authorization': 'Bearer your-secret' }
    },
    webhookType: 'CompletedWebHookPayload',
    callAdditionalData: { userId: 'test-123' }
  })
});

const result = await response.json();
console.log('Success:', result.success);
console.log('HTTP Status:', result.httpStatus);
console.log('Time:', result.timeTaken, 'ms');

Example: Test webhook response

{
  "success": true,
  "httpStatus": 200,
  "responseData": { "received": true },
  "timeTaken": 245
}

Testing webhooks that use call data

A webhook that contains variables such as {{callAdditionalData.orderId}} needs stand-in values, because that data exists only on a real call.

Dashboard: fill in Test values for custom data, which appears when the webhook references custom data, then click Test Webhook or Test Tool. Sample values are not saved.
API: pass callAdditionalData and agentAdditionalData in the test request, as in the example above, and include the webhook’s customSettings.

Check Request Sent in the dashboard, or sentRequest in the API response, to see the final URL, headers and body. A variable that still appears with its braces had no value in the test data. See Request Templating for the full reference.

Testing with webhook.site

Visit webhook.site
Copy your unique URL
Use as webhook URL in test API
Inspect full request details

Local Testing with ngrok

Setup

# Install ngrok
brew install ngrok  # macOS
# or download from ngrok.com

# Authenticate
ngrok config add-authtoken YOUR_TOKEN

# Start tunnel
ngrok http 3000
# Output: https://abc123.ngrok.io -> localhost:3000

Local Webhook Server

const express = require('express');

const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  console.log('Webhook received:', req.body.type);

  // Handle by type
  switch (req.body.type) {
    case 'StartWebHookPayload':
      console.log('Call started:', req.body.callId);
      break;
    case 'CompletedWebHookPayload':
      console.log('Call completed:', req.body.callId);
      break;
    case 'FailedWebHookPayload':
      console.error('Call failed:', req.body.errorMessage);
      break;
  }

  res.status(200).json({ received: true });
});

app.listen(3000, () => console.log('Server on port 3000'));

Testing Workflow

# Terminal 1: Start server
node webhook-server.js

# Terminal 2: Start ngrok
ngrok http 3000

# Terminal 3: Test
curl -X POST https://blackbox.dasha.ai/api/v1/webhooks/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webHook": { "url": "https://abc123.ngrok.io/webhook" },
    "webhookType": "CompletedWebHookPayload"
  }'

Access ngrok web interface at http://127.0.0.1:4040 to inspect and replay requests.

Testing Event Types

StartWebHookPayload

await fetch('https://blackbox.dasha.ai/api/v1/webhooks/test', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    webHook: { url: 'https://your-server.com/webhook' },
    webhookType: 'StartWebHookPayload',
    agentAdditionalData: { companyName: 'Acme Corp' },
    callAdditionalData: { customerId: 'cust_123' }
  })
});

ToolWebHookPayload

await fetch('https://blackbox.dasha.ai/api/v1/webhooks/test', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    webHook: { url: 'https://your-server.com/webhook' },
    webhookType: 'ToolWebHookPayload',
    toolName: 'check_availability',
    toolArguments: { date: '2025-01-20', time: '14:00' }
  })
});

Testing Retry Behavior

Simulate failures to test retry handling:

let attemptCount = 0;

app.post('/webhook', (req, res) => {
  attemptCount++;
  console.log(`Attempt ${attemptCount}`);

  // Fail first 2 attempts
  if (attemptCount <= 2) {
    return res.status(500).json({ error: 'Temporary error' });
  }

  res.status(200).json({ received: true });
});

Testing Idempotency

Handle duplicate webhooks:

const processed = new Set();

app.post('/webhook', (req, res) => {
  const id = `${req.body.callId}_${req.body.timestamp}`;

  if (processed.has(id)) {
    console.log('Duplicate webhook, skipping');
    return res.status(200).json({ duplicate: true });
  }

  processed.add(id);
  processWebhook(req.body);

  res.status(200).json({ received: true });
});

Debugging

Common Issues

Issue	Solution
Connection refused	Verify URL is publicly accessible
Timeout	Respond within 30s, use async processing
401 Unauthorized	Check authentication headers
500 errors	Check server logs, add error handling

Response Time Requirements

Event Type	Max Response Time
StartWebHookPayload	5 seconds
ToolWebHookPayload	10 seconds
Other webhooks	30 seconds

Quick Response Pattern

app.post('/webhook', (req, res) => {
  // Respond immediately
  res.status(200).json({ received: true });

  // Process asynchronously
  setImmediate(() => {
    processWebhook(req.body);
  });
});

Pre-Production Checklist

Webhook URL is publicly accessible
Response time under required limit
Idempotency handling for duplicates
Error handling for all scenarios
Logging enabled for debugging
Tested all event types

Next Steps

Configuring Webhooks — Set up webhook endpoints
Webhook Events — Event types and payloads

Introduction

Create

Test

Deploy

Monitor

Advanced Features

Troubleshooting

Testing Methods

Testing webhooks that use call data

Testing with webhook.site

Local Testing with ngrok

Testing Event Types

Debugging

Common Issues

Response Time Requirements

Pre-Production Checklist

Next Steps

​Testing Methods

​Testing webhooks that use call data

​Testing with webhook.site

​Local Testing with ngrok

​Testing Event Types

​Debugging

​Common Issues

​Response Time Requirements

​Pre-Production Checklist

​Next Steps

Testing Methods

Testing webhooks that use call data

Testing with webhook.site

Local Testing with ngrok

Testing Event Types

Debugging

Common Issues

Response Time Requirements

Pre-Production Checklist

Next Steps