Webhooks

Webhooks notify your systems when events happen in FyVault.

Events

Event	Fires when
`SECRET_CREATED`	New secret added
`SECRET_UPDATED`	Secret value changed
`SECRET_ROTATED`	Secret rotated
`SECRET_DELETED`	Secret removed
`DEVICE_REGISTERED`	New device registered
`DEVICE_REVOKED`	Device access removed
`DEVICE_BOOT`	Device fetches secrets
`POLICY_VIOLATION`	A policy rule is broken

Payload Format

Webhook Payloadjson

{
  "event": "SECRET_CREATED",
  "timestamp": "2026-04-02T12:00:00.000Z",
  "org_id": "cmnh...",
  "data": {
    "secret_id": "cm12...",
    "name": "OPENAI_API_KEY",
    "secret_type": "API_KEY"
  }
}

Verifying Signatures

Every webhook includes an X-FyVault-Signature header (HMAC-SHA256):

verify-webhook.jsjavascript

const crypto = require('crypto');

const expected = crypto
  .createHmac('sha256', process.env.WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');

const valid = req.headers['x-fyvault-signature'] === expected;

Retry Policy

Failed deliveries retry 3 times with exponential backoff:

1st retry

1 min

2nd retry

5 min

3rd retry

30 min