Webhooks

WhiteBooks delivers async events via outbound webhooks. Register a URL per event type (or one URL for all), verify the HMAC-SHA256 signature on each delivery, respond HTTP 200 within 10s. Failed deliveries retry 5 times over 24 hours before dead-lettering.

Event types

Payload shape

POST https://your.app/webhooks/whitebooks
Content-Type: application/json
X-WhiteBooks-Signature: t=1779839020,v1=5f43a8c2...
X-WhiteBooks-Event: irn.generated

{
  "id":      "evt_abc123",
  "type":    "irn.generated",
  "created": "2026-05-27T08:30:00Z",
  "data": {
    "irn":       "f5ab8...",
    "ackNo":     "112010024576789",
    "ackDate":   "2026-05-27 08:29:45",
    "signedQr":  "eyJhbGc..."
  }
}

Verify the signature

// Node.js
import { wb } from 'whitebooks-sdk';

app.post('/webhooks/whitebooks', (req, res) => {
  const ok = wb.webhooks.verify(req.rawBody, req.headers['x-whitebooks-signature'], process.env.WB_WEBHOOK_SECRET);
  if (!ok) return res.sendStatus(401);
  // handle req.body.type ...
  res.sendStatus(200);
});

Retry policy

Failed deliveries (non-2xx response or timeout > 10s) retry 5 times: 1m → 5m → 30m → 2h → 12h. After 5 failures the event moves to dead-letter and surfaces in the dashboard with the last response body for debugging.

Related

Part of the WhiteBooks developer documentation cluster. See /llms.txt for the full machine-readable site index. Last updated 27 May 2026.