Webhooks
Build custom integrations with real-time event notifications.
Creating a Webhook
- Go to Settings → Integrations → Webhooks
- Click Add Webhook
- Enter your endpoint URL
- Select events to subscribe to
- Optionally add a secret for signature verification
Event Types
| Event | Description |
|---|---|
| scan.started | Scan has begun |
| scan.completed | Scan finished successfully |
| scan.failed | Scan encountered an error |
| finding.created | New vulnerability discovered |
| finding.resolved | Vulnerability confirmed fixed |
Payload Format
Example finding.created payload:
{
"event": "finding.created",
"timestamp": "2026-01-23T10:30:00Z",
"data": {
"id": "find_abc123",
"scan_id": "scan_xyz789",
"severity": "critical",
"title": "SQL Injection",
"description": "Unauthenticated SQL injection in login endpoint",
"url": "https://example.com/api/login",
"parameter": "username",
"cwe": "CWE-89",
"remediation": "Use parameterized queries...",
"dashboard_url": "https://app.hackerbot.io/findings/find_abc123"
}
}Signature Verification
Verify webhook authenticity using the signature header:
// Node.js example
const crypto = require('crypto');
function verifySignature(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(`sha256=${expected}`)
);
}
// In your handler
const signature = req.headers['x-hackerbot-signature'];
if (!verifySignature(req.body, signature, process.env.WEBHOOK_SECRET)) {
return res.status(401).send('Invalid signature');
}Retry Policy
Failed webhook deliveries are retried automatically:
- Up to 5 retry attempts
- Exponential backoff (1min, 5min, 30min, 2hr, 12hr)
- Webhooks disabled after 7 days of failures
- View delivery logs in your dashboard