Overview
Webhooks allow you to receive real-time HTTP notifications when events occur in your KrosAI account.
Setup
Follow the steps below to configure a webhook endpoint from your KrosAI Dashboard.
1
Go to the Webhooks page
Go to Developers → Webhooks in the Dashboard.
2
Create a webhook
Click Create Webhook.
3
Enter your endpoint
Enter your endpoint URL.
4
Select events
Select the events you want to subscribe to.
5
Save and copy secret
Save the webhook and copy the signing secret.
Keep your signing secret safe — you will need it to verify incoming webhook payloads.
Available Events
Subscribe only to the events your application needs to reduce unnecessary traffic.
| Call connected |
| Call ended |
| Call failed to connect |
| Recording available |
| Transcript ready |
Payload Structure
Every webhook payload follows the same envelope structure regardless of event type.
{
"id": "evt_abc123",
"event": "call.ended",
"timestamp": "2025-01-12T10:30:00Z",
"data": {
"call_id": "call_xyz789",
"from_number": "+2348012345678",
"to_number": "+14155551234",
"direction": "outbound",
"duration": 180,
"cost_cents": 12,
"status": "completed"
}
}
Signature Verification
Always verify the webhook signature before processing any payload. Skipping this step exposes your endpoint to spoofed requests.
Verify the X-Webhook-Signature header:
const crypto = require('crypto');
function verifySignature(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(payload, 'utf8')
.digest('hex');
return `sha256=${expected}` === signature;
}
Retry Policy
Your endpoint must respond with HTTP 2xx within 10 seconds. Failure to do so will trigger the retry schedule below.
1 | Immediate |
2 | 1 minute |
3 | 5 minutes |
4 | 30 minutes |
5 | 2 hours |
After 5 failed attempts, the webhook will be disabled automatically. You must re-enable it manually from the Dashboard.
On this page
- Overview