Webhooks

Webhooks are how Pierflow tells your system the world has changed — without you polling. Every event carries a signature; verify it before acting.

Event catalogue#

Subscribing#

{
  "url": "https://example.com/webhooks/pierflow",
  "events": ["policy.issued", "premium.paid", "claim.approved"]
}

Signature verification#

Every delivery includes X-Pierflow-Signature: t=...,v1=.... Recompute the signature over <timestamp>.<raw-body> with your endpoint secret using HMAC-SHA256 and compare in constant time.

import crypto from 'node:crypto';

export function verifyPierflow(rawBody: string, header: string, secret: string) {
  const [tPart, sigPart] = header.split(',');
  const t = tPart.split('=')[1];
  const sig = sigPart.split('=')[1];
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

Retries#

Pierflow retries failed deliveries with exponential backoff: immediate, then 30s, 2m, 10m, 1h, 6h, 24h. After 7 failures the webhook is marked dead and an alert email is sent.