Documentation Index Fetch the complete documentation index at: https://docs.blackbox.dasha.ai/llms.txt
Use this file to discover all available pages before exploring further.
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
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 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
# 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
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' ));
# 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
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' }
})
});
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 });
});
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
app. post ( '/webhook' , ( req , res ) => {
// Respond immediately
res. status ( 200 ). json ({ received: true });
// Process asynchronously
setImmediate (() => {
processWebhook (req.body);
});
});
Pre-Production Checklist
Next Steps