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:
- alert.critical, alert.warning, alert.info, alert.resolved
- containment.triggered (a server was locked down), lockdown.disabled
- ban.added, ban.removed — an IP was banned or unbanned by an operator, an approved request, an API call, or automatically. An automatic ban covers every server in your organization and is sent once, with servers giving how many; an expiring one likewise. Bulk threat-feed syncs are not sent
- agent.offline — once per outage, when an agent has gone silent; agent.online when it is back
- investigation.opened, ttp.matched
- approval.pending — Vigilhold wants to do something that needs a person to approve it (approval_id, action, server_id)
- cve.new — after a scan, the new critical or high vulnerabilities it found on your servers, in one event: count, message, and vulnerabilities (each with id, package, severity, cvss, servers, hostnames, url). Exploited ones arrive as alert.critical instead
- custom.event — every event pushed to the Event Ingest API
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:
- X-Watch-Event — the event name
- X-Watch-Signature — sha256= followed by the hex HMAC-SHA256 of the raw body, keyed with the endpoint's secret
- X-Watch-Timestamp — when this attempt was sent (not signed; don't rely on it)
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
- Always verify the signature — never trust the payload without it.
- Return HTTP 200 immediately and process the event asynchronously to stay within the 8-second timeout.
- Subscribe an endpoint to * in development to see everything, then narrow it to the events you need.