@distyra/sdk 0.6.0 → 0.7.0

package/README.md

@@ -77,6 +77,43 @@ Note: `resolution.retryable` is a different signal. It is `true` only for a tran
 backend error (`timed_out` / `transient_error`), which you retry within seconds. See the
 full resolution-and-retries guide at <https://api.distyra.com/docs>.
 
+## Verifying webhooks
+
+Distyra signs every webhook delivery with a Stripe-shape header:
+
+```
+X-Distyra-Signature: t=<unix>,v1=<hmac_sha256_hex>
+```
+
+`verifyWebhook` checks it (HMAC-SHA256 over `"<t>.<rawBody>"`, keyed by the
+endpoint's signing secret, with replay protection). Always verify against the
+**raw request body**, before JSON parsing — re-serializing changes the bytes and
+breaks the signature.
+
+```ts
+import { verifyWebhook } from '@distyra/sdk';
+
+// Express — capture the raw body, e.g. app.use(express.raw({ type: 'application/json' }))
+app.post('/webhooks/distyra', (req, res) => {
+  const raw = req.body.toString('utf8');
+  const result = verifyWebhook(
+    process.env.DISTYRA_WEBHOOK_SECRET!,
+    raw,
+    req.header('X-Distyra-Signature'),
+  );
+  if (!result.ok) return res.status(400).send(result.reason);
+
+  const event = JSON.parse(raw);
+  // ... handle event ...
+  res.sendStatus(200);
+});
+```
+
+It returns `{ ok: true, timestamp }` or `{ ok: false, reason }` where `reason` is
+`'malformed'`, `'stale'`, or `'no_match'`. The default replay window is 5 minutes
+(`DEFAULT_TOLERANCE_SECONDS`); override it with `{ toleranceSeconds }`. Uses
+`node:crypto`, so it runs server-side (Node 18+).
+
 ## Lower-level access
 
 The generated `paths` and `operations` types are re-exported if you want to build your own `openapi-fetch` client or reference response shapes directly: