Webhooks

Set up real-time notifications for scan events using webhooks. Get instant updates when scans complete, fail, or find critical issues.

Real-time notificationsEvent-driven integrationJSON payloads

Available Events

scan.startedInfo

Triggered when a scan begins processing

scan.progressProgress

Periodic updates during scan execution

scan.completedSuccess

Triggered when a scan finishes successfully

scan.failedError

Triggered when a scan encounters an error

issue.criticalWarning

Triggered when critical security issues are found

scan.timeoutTimeout

Triggered when a scan exceeds time limits

Setting Up Webhooks

Create Webhook Endpoint

1. Create an HTTPS endpoint in your application that can receive POST requests

2. The endpoint should respond with 200 OK within 5 seconds

3. Implement signature verification for security

4. Handle duplicate events gracefully

Required Headers

Content-Type: application/json

X-Cortex-Signature

X-Cortex-Event

X-Cortex-Delivery

Response Requirements

• Status: 200 OK

• Timeout: < 5 seconds

• Idempotent handling

• No authentication required

Registering Webhooks

Via Dashboard

Navigate to Settings → Webhooks
Click "Add Webhook"
Enter your endpoint URL
Select events to subscribe to
Set webhook secret for verification
Test the webhook with sample data

Via API

Create Webhook

POST /webhooks
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "url": "https://your-app.com/webhooks/cortex",
  "events": ["scan.completed", "issue.critical"],
  "secret": "your-webhook-secret",
  "active": true
}

Security & Verification

⚠️ Security Best Practices

• Always use HTTPS endpoints
• Verify webhook signatures
• Validate event payloads
• Implement rate limiting
• Use webhook secrets for authentication

Signature Verification

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  return signature === `sha256=${expectedSignature}`;
}

Event Validation

• Check event type matches expected

• Validate payload structure

• Verify timestamps are recent

• Handle duplicate events

• Implement idempotent processing

Example Payloads

Scan Completed Event

{
  "event": "scan.completed",
  "id": "evt_1234567890",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    "scan_id": "scan_abc123",
    "repo_url": "https://github.com/user/repo",
    "status": "completed",
    "score": 85,
    "issues_count": 12,
    "duration_seconds": 45
  }
}

Critical Issue Found

{
  "event": "issue.critical",
  "id": "evt_1234567891",
  "timestamp": "2024-01-01T12:05:00Z",
  "data": {
    "scan_id": "scan_abc123",
    "issue_id": "issue_xyz789",
    "severity": "critical",
    "title": "SQL Injection Vulnerability",
    "file": "api/user.js",
    "line": 42
  }
}

Troubleshooting

Common Issues

Webhook not firing

Check endpoint is accessible and returns 200 OK

Signature verification fails

Ensure webhook secret matches in both places

Duplicate events received

Implement idempotent handling using event IDs

Testing Webhooks

• Use webhook testing tools like ngrok for local development

• Test with sample payloads from the dashboard

• Monitor webhook delivery logs

• Implement comprehensive error logging

• Set up alerts for webhook failures

Test Command

curl -X POST your-endpoint-url -H "Content-Type: application/json" -d '{"test": "data"}'

Webhook Management

→ Manage Webhooks → API Reference → Authentication

Webhook Limits

• 10 webhooks per account

• 100 events/second burst

• 30 second timeout

• 3 retry attempts

Supported Integrations

🔗 Slack

💬 Discord

📧 Email

🔧 Custom Apps

📊 Monitoring Tools

Example Use Cases

• CI/CD pipeline notifications

• Security dashboard updates

• Team alerting for critical issues

• Audit log integration

• Compliance reporting

Need Help?

→ Webhook Support → FAQ