Webhooks

Receiving events

Register a HTTPS endpoint in the dashboard. FinStack will POST JSON events to it:

{
  "id": "01927b3e-...",
  "type": "payment.captured",
  "tenant_id": "...",
  "created_at": "2026-06-01T00:00:00Z",
  "data": {
    "payment": { ... }
  }
}

Verifying signatures

Every request carries an X-FinStack-Signature header. Verify it before processing:

import { createHmac, timingSafeEqual } from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex'),
  );
}

Always use a constant-time comparison — === is vulnerable to timing attacks.

Retry policy

FinStack retries failed deliveries up to 3 times with exponential backoff: 1 min, 5 min, 30 min. An endpoint is considered failed if it returns a non-2xx status or times out after 30 seconds.

Event types

Event	Trigger
payment.created	New payment
payment.captured	Payment captured
payment.cancelled	Payment cancelled
payment.refunded	Full or partial refund
customer.created	New customer
customer.updated	Customer profile updated