Webhooks
Receive real-time notifications from DeepV-ADK.Overview
Webhooks allow you to receive HTTP callbacks when specific events occur in your DeepV-ADK account.Setting Up Webhooks
Via Dashboard
Via API
``bash
curl -X POST https://api.deepv36.com/v1/webhooks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-domain.com/webhook",
"events": ["analysis.completed"],
"secret": "your_secret_key"
}'
`
Available Events
| Event | Description |
|-------|-------------|
| analysis.completed | Analysis finished processing |
| analysis.failed | Analysis encountered an error |
| batch.started | Batch processing started |
| batch.completed | Batch processing finished |
| applicant.updated | Applicant data was updated |
Webhook Payload
Example payload for analysis.completed:
`json
{
"event": "analysis.completed",
"timestamp": "2025-11-23T10:30:00Z",
"data": {
"id": "req_1234567890",
"status": "completed",
"riskScore": 750,
"decision": "APPROVE",
"applicant": {
"id": "app_9876543210"
}
}
}
`
Verifying Webhooks
Verify webhook authenticity using the signature:
`typescript
import crypto from 'crypto';
function verifyWebhook(payload: string, signature: string, secret: string): boolean {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
`
Handling Webhooks
Express.js Example
`typescript
import express from 'express';
const app = express();
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-deepv-signature'] as string;
const payload = req.body.toString();
if (!verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
return res.status(401).send('Invalid signature');
}
const event = JSON.parse(payload);
// Process the event
console.log('Received event:', event.event);
res.status(200).send('OK');
});
`
Best Practices
Respond Quickly
Return a 200 response immediately, then process asynchronously:
`typescript
app.post('/webhook', async (req, res) => {
// Respond immediately
res.status(200).send('OK');
// Process asynchronously
processWebhook(req.body).catch(console.error);
});
`
Implement Retry Logic
Handle failures gracefully:
`typescript
async function processWebhook(event: WebhookEvent, retries = 3) {
try {
await handleEvent(event);
} catch (error) {
if (retries > 0) {
await delay(1000);
return processWebhook(event, retries - 1);
}
throw error;
}
}
`
Idempotency
Use event IDs to prevent duplicate processing:
`typescript
const processedEvents = new Set();
function handleEvent(event: WebhookEvent) {
if (processedEvents.has(event.id)) {
return; // Already processed
}
// Process event
processedEvents.add(event.id);
}
`
Testing Webhooks
Use the test endpoint to trigger sample events:
`bash
curl -X POST https://api.deepv36.com/v1/webhooks/test \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"webhookId": "webhook_123",
"event": "analysis.completed"
}'
`
Troubleshooting
Webhook Not Receiving Events
Verify URL is publicly accessible
Check firewall/security group settings
Ensure SSL certificate is valid
Review webhook logs in dashboard
Signature Verification Failing
Use raw request body (don't parse JSON first)
Verify webhook secret is correct
Check header name is exact: x-deepv-signature`
Next Steps
Found an issue? Help us improve this page.