API: Webhooks

Register endpoints, subscribe to event types, and verify HMAC signatures.

Creating an endpoint

An org admin creates webhook endpoints in the dashboard (Settings → Webhooks): a name, an HTTPS URL, and the events to send. The signing secret is shown once.

API keys cannot create or change endpoints — a key that could add a webhook could send every event to any address. With webhooks:read a key can list endpoints (GET /api/v1/webhooks); with webhooks:write it can rotate an endpoint's secret (POST /api/v1/webhooks/:id/rotate-secret) and replay a delivery (POST /api/v1/webhooks/:webhookId/replay/:deliveryId).

Endpoints must be public HTTPS addresses. Private, loopback and link-local addresses are refused, and checked again at every delivery.

Event subscriptions and wildcards

Subscribe to any of these, or * for all:

GET /api/webhooks/events returns the current list. A new alert of a type you marked a false positive on that server is not sent.

Signature verification

Every delivery is a POST with these headers, whose X-Watch- names come from the product's earlier name:

The body is { "schema_version": 1, "event": "...", "ts": <ms>, "data": { ... } }. Its ts is covered by the signature, so use it, not the header, for any age check.

// Node.js / Express
app.post('/vigilhold-webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const expected = 'sha256=' + crypto
      .createHmac('sha256', process.env.VIGILHOLD_WEBHOOK_SECRET)
      .update(req.body)            // the raw bytes, before JSON.parse
      .digest('hex');
    const got = String(req.headers['x-watch-signature'] ?? '');
    if (got.length !== expected.length ||
        !crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))) {
      return res.status(401).end();
    }
    const delivery = JSON.parse(req.body);
    // delivery.event, delivery.ts, delivery.data
    res.sendStatus(200);
  }
);

Delivery guarantees and retry policy

A delivery succeeds when your endpoint answers 2xx within 8 seconds. Redirects count as failures.

A failed delivery is retried up to 5 times after the first attempt, starting on the next background pass; each retry sends the same body. After that it is marked failed. GET /api/webhooks/:id/deliveries lists test sends and replays.

A delivery can arrive more than once and out of order: deduplicate on the event name and data, and order by ts.

Tips

All Vigilhold docs · Start a 14-day free trial