Webhooks

Subscribe to platform events. Endpoints are HMAC-signed, with at-least-once delivery and exponential-backoff retries.

Signing

Each request carries an X-Valienz-Signature header of the form t=…,v1=…. Concatenate t + . + raw body, HMAC-SHA256 with the per-endpoint secret, hex-encode, and constant-time compare with v1.

import crypto from 'crypto';

function verify(signatureHeader: string, body: string, secret: string) {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map((p) => p.split('=') as [string, string]),
  );
  const expected = crypto
    .createHmac('sha256', secret)
    .update(parts.t + '.' + body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(parts.v1, 'hex'),
  );
}

Retries & DLQ

A non-2xx response (or no response within 10 seconds) triggers up to 6 retries: 1m, 5m, 30m, 2h, 12h, 24h. After the 6th failure the delivery lands in the per-tenant DLQ. Replay from the dashboard or the API.

Event catalog

The full list lives in the dashboard's event picker (/settings/webhooks → Add endpoint). Group your subscription by product; you almost always want *.delivered + *.failed rather than every intermediate state.