Webhooks
Webhooks provide a way for Unizo to send real-time notifications to your application when specific events occur. Instead of continuously polling our APIs, webhooks allow you to receive instant updates about changes to your integrations.
How Webhooks Work
When an event occurs (such as a new vulnerability being detected or a deployment completing), Unizo sends an HTTP POST request to a URL you specify. This request contains details about the event that occurred.
Setting Up Webhooks
1. Create a Webhook Endpoint
First, create an endpoint in your application to receive webhook events:
// Express.js example
app.post('/webhooks/unizo', (req, res) => {
const event = req.body;
// Verify the webhook signature (recommended)
if (!verifySignature(req.headers['x-unizo-signature'], req.body)) {
return res.status(401).send('Unauthorized');
}
// Process the event
switch (event.type) {
case 'vulnerability.detected':
handleVulnerabilityDetected(event.data);
break;
case 'deployment.completed':
handleDeploymentCompleted(event.data);
break;
default:
console.log(`Unhandled event type: ${event.type}`);
}
res.status(200).send('OK');
});
2. Register Your Webhook
Use the Unizo API to register your webhook endpoint:
curl -X POST https://api.unizo.ai/v1/webhooks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-app.com/webhooks/unizo",
"events": ["vulnerability.detected", "deployment.completed"],
"secret": "your-webhook-secret"
}'
Event Types
Unizo supports various event types across different APIs:
Security Events
vulnerability.detected
- New vulnerability foundsecurity.alert
- Security alert triggeredcompliance.violation
- Compliance rule violated
Development Events
deployment.started
- Deployment initiateddeployment.completed
- Deployment finishedbuild.failed
- Build process failed
Integration Events
connection.established
- New integration connectedconnection.failed
- Integration connection failedsync.completed
- Data synchronization finished
Webhook Payload Structure
All webhook payloads follow a consistent structure:
{
"id": "evt_1234567890",
"type": "vulnerability.detected",
"timestamp": "2023-12-01T10:30:00Z",
"data": {
"vulnerability": {
"id": "vuln_123",
"severity": "high",
"title": "SQL Injection in user authentication",
"description": "...",
"affected_assets": ["app-server-1", "database-1"]
}
},
"metadata": {
"source": "vulnerability-scanner",
"integration_id": "int_456"
}
}
Security
Signature Verification
Unizo signs webhook payloads using your webhook secret. Always verify signatures to ensure authenticity:
const crypto = require('crypto');
function verifySignature(signature, payload, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload, 'utf8')
.digest('hex');
return signature === `sha256=${expectedSignature}`;
}
Best Practices
- Use HTTPS: Always use HTTPS endpoints for webhook URLs
- Verify signatures: Implement signature verification for all webhooks
- Handle retries: Implement proper retry logic for failed deliveries
- Idempotency: Design your webhook handlers to be idempotent
- Timeout handling: Respond within 30 seconds to avoid retries
Testing Webhooks
Use our webhook testing tool to validate your endpoints:
# Test your webhook endpoint
curl -X POST https://api.unizo.ai/v1/webhooks/test \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"webhook_id": "wh_123",
"event_type": "vulnerability.detected"
}'
Troubleshooting
Common Issues
-
Webhook not receiving events
- Check your endpoint URL is accessible
- Verify your webhook is properly registered
- Ensure your server responds with 2xx status codes
-
Signature verification failing
- Confirm you're using the correct webhook secret
- Check your signature calculation implementation
- Verify the request body is read correctly
-
Duplicate events
- Implement idempotency in your handlers
- Check for network issues causing retries
Webhook Logs
View webhook delivery logs in the Unizo Console:
- Navigate to Settings → Webhooks
- Click on your webhook
- View the Delivery Log tab
Rate Limits
Webhook deliveries are subject to rate limits:
- Maximum 1000 events per minute per webhook
- Failed deliveries are retried with exponential backoff
- Maximum 3 retry attempts per event