Webhooks

Register an endpoint (POST /api/v1/webhooks) with the events you care about; the signing secret is returned once. Delivery is at-least-once — make handlers idempotent (dedupe on the delivery id / transaction id).

Security

Every delivery is signed with HMAC-SHA256 over timestamp.bodyand includes X-PayChain-Signature + X-PayChain-Timestamp (replay protection). Verify before trusting:

import { PayChainClient } from '@paychain/sdk';

// signature = HMAC-SHA256(secret, `${timestamp}.${rawBody}`)
const ok = PayChainClient.verifyWebhook(
  secret,
  rawBody,
  req.headers['x-paychain-signature'],
  req.headers['x-paychain-timestamp'],
);
if (!ok) return res.status(400).end();  // bad signature or stale timestamp

Events

Retries use exponential backoff; exhausted deliveries move to a dead-letter state and can be replayed.