Skip to main content

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 found
  • security.alert - Security alert triggered
  • compliance.violation - Compliance rule violated

Development Events

  • deployment.started - Deployment initiated
  • deployment.completed - Deployment finished
  • build.failed - Build process failed

Integration Events

  • connection.established - New integration connected
  • connection.failed - Integration connection failed
  • sync.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

  1. Use HTTPS: Always use HTTPS endpoints for webhook URLs
  2. Verify signatures: Implement signature verification for all webhooks
  3. Handle retries: Implement proper retry logic for failed deliveries
  4. Idempotency: Design your webhook handlers to be idempotent
  5. 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

  1. Webhook not receiving events

    • Check your endpoint URL is accessible
    • Verify your webhook is properly registered
    • Ensure your server responds with 2xx status codes
  2. Signature verification failing

    • Confirm you're using the correct webhook secret
    • Check your signature calculation implementation
    • Verify the request body is read correctly
  3. Duplicate events

    • Implement idempotency in your handlers
    • Check for network issues causing retries

Webhook Logs

View webhook delivery logs in the Unizo Console:

  1. Navigate to SettingsWebhooks
  2. Click on your webhook
  3. 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

Next Steps