Webhooks

Webhooks let your server receive scan status updates automatically instead of polling GET /v1/scans/:id/status. When a scan progresses, completes, or fails, we send an HTTP POST request to your registered URL.

Overview

The typical scan flow without webhooks requires polling:

1. Create a scan via POST /v1/scans
2. Poll GET /v1/scans/:id/status every few seconds
3. Stop polling when status is completed or error

With webhooks, step 2 is replaced — your server receives updates automatically as they happen.

Registering a webhook

Webhooks are configured through the Enhub dashboard — not via the API. Navigate to Settings → Webhooks in your project to register, update, or delete webhook endpoints.

When creating a webhook you'll configure:

After saving, the dashboard will display your signing secret. Store it securely — you'll need it to verify webhook signatures. The secret is only shown once upon creation.

Event types

Subscribe to any combination of these events when registering a webhook:

Payload format

When an event fires, we send an HTTP POST request to your registered URL with a JSON body.

{
  "event": "scan.completed",
  "webhookId": "wh_cml3ucftb0001yqzvr4jgakw5",
  "timestamp": "2026-03-01T12:05:32.000Z",
  "data": {
    "id": "cml3ucftb0001yqzvr4jgakw5",
    "status": "completed",
    "progression": 100,
    "hasError": false,
    "createdAt": "2026-03-01T12:00:00.000Z"
  }
}

{
  "event": "scan.failed",
  "webhookId": "wh_cml3ucftb0001yqzvr4jgakw5",
  "timestamp": "2026-03-01T12:05:32.000Z",
  "data": {
    "id": "cml3ucftb0001yqzvr4jgakw5",
    "status": "error",
    "progression": 45,
    "hasError": true,
    "errorMessage": "Scan timed out na 12 minuten. De berekening duurde te lang — probeer het opnieuw.",
    "createdAt": "2026-03-01T12:00:00.000Z"
  }
}

{
  "event": "scan.status_update",
  "webhookId": "wh_cml3ucftb0001yqzvr4jgakw5",
  "timestamp": "2026-03-01T12:02:15.000Z",
  "data": {
    "id": "cml3ucftb0001yqzvr4jgakw5",
    "status": "processing",
    "progression": 45,
    "hasError": false,
    "createdAt": "2026-03-01T12:00:00.000Z"
  }
}

Verifying signatures

Every webhook delivery includes an X-Enhub-Signature header containing an HMAC-SHA256 signature of the raw request body, using your webhook secret as the key. Always verify this signature to ensure the request is from Enhub.

import crypto from 'crypto';

function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

// Express.js example
app.post('/webhooks/enhub', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-enhub-signature'];
  const secret = process.env.ENHUB_WEBHOOK_SECRET;

  if (!verifyWebhook(req.body, signature, secret)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  console.log(`Received ${event.event} for scan ${event.data.id}`);

  // Process the event...
  res.status(200).send('OK');
});

Retry policy

If your endpoint doesn't return a 2xx status code, we retry the delivery with exponential backoff:

After 4 failed attempts, the delivery is marked as failed. If a webhook endpoint consistently fails, it will be automatically deactivated after 10 consecutive failures.

Managing webhooks

Webhooks are managed entirely through the Enhub dashboard under Settings → Webhooks. From there you can:

• View all registered webhooks and their delivery history
• Edit the URL, subscribed events, or active status
• Pause deliveries by toggling a webhook to inactive
• Delete a webhook registration permanently
• Rotate the signing secret if it has been compromised