Skip to main content

Webhooks

Webhooks push platform events to an HTTPS endpoint you control, so your integration reacts to vault, stream, attachment and permission activity without polling.

The complete reference — the full event table, payload shape, signature verification, retry behaviour, destination rules and resource filters — lives at Webhooks.

The essentials​

Register a webhook against the notifications resource:

curl -X POST "https://api.filedgr.network/notifications/webhooks" \
  -H "x-api-key: $FILEDGR_API_KEY" -H "x-api-secret: $FILEDGR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/filedgr",
    "event_types": ["vault.created", "data_attachment.completed"],
    "description": "Production listener",
    "secret": "a-long-random-string"
  }'

The field is event_types, not events. Enablement is a status of ACTIVE, PAUSED or DISABLED — there is no boolean active field.

Payload​

Deliveries carry three snake_case keys, and there is no event id:

{
  "event_type": "vault.created",
  "timestamp": "2026-01-15T10:30:00.123456",
  "data": { }
}

The timestamp is naive — no trailing Z and no offset.

Headers​

HeaderValue
Content-Typeapplication/json
User-AgentFiledgr-Webhook/1.0
X-Filedgr-EventThe event type
X-Filedgr-Signaturesha256=<hex>, only when the config has a secret

Verifying the signature​

The signature is an HMAC-SHA256 of the raw request body, hex-encoded, and the header carries a sha256= prefix. Compare against the full prefixed string:

const crypto = require('crypto');

function verifySignature(rawBody, header, secret) {
  const expected =
    'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(header || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Hash the raw body, before any JSON parsing or re-serialisation.

Responding​

Return a 2xx as soon as you have durably accepted the event, and do your processing asynchronously — a delivery that takes longer than 30 seconds counts as a failure. Make your handler idempotent: a delivery can be re-sent.

Next steps​