Write a webhook subscriber onboarding guide with HMAC verification code samples

[greatest0fallt1me]

Description

The backend fans out HMAC-signed draw_confirmed webhooks via src/services/drawWebhookService.ts, which documents the signature contract (X-Webhook-Signature: sha256=<hex HMAC over raw body>, X-Webhook-Timestamp, User-Agent: Creditra-Webhook/1.0) and instructs subscribers to verify the HMAC in constant time, reject stale timestamps, and dedupe by data.drawId. The management routes live in src/routes/webhook.ts, but there is no dedicated subscriber-facing onboarding doc — docs/API.md §Webhooks is referenced from the code yet a step-by-step verification guide with runnable samples is missing. This issue adds that guide.

Requirements and context

• Create docs/webhook-subscribers.md covering: the exact WebhookPayload shape from drawWebhookService.ts (event, timestamp, data.{ledger,contractId,drawAmount,drawId,borrowerWallet,creditLineId,horizonTimestamp}), the three signature headers, and the retry/backoff knobs (WEBHOOK_MAX_RETRIES, WEBHOOK_INITIAL_BACKOFF_MS, WEBHOOK_BACKOFF_MULTIPLIER, WEBHOOK_TIMEOUT_MS).
• Provide a correct, copy-pasteable Node.js verification snippet using crypto.createHmac('sha256', secret) and crypto.timingSafeEqual, computing the HMAC over the raw request body (matching generateSignature in the service) — emphasize verifying before JSON parsing.
• Document timestamp-tolerance checking against X-Webhook-Timestamp and idempotent handling keyed on data.drawId, consistent with the service docstring.
• Document the operator endpoints from src/routes/webhook.ts (GET /api/webhooks/config, POST /api/webhooks/test, GET /api/webhooks/health) and link the guide from docs/API.md, docs/README.md, and the README documentation index.
• Non-functional: every claim must match the code as written (no invented headers, fields, or env vars); keep the doc free of real secrets.

Acceptance criteria

• docs/webhook-subscribers.md exists and documents the payload, headers, and env knobs exactly as implemented.
• A correct HMAC-SHA256 verification sample (over the raw body, constant-time compare) is included.
• Timestamp-tolerance and drawId dedup guidance is documented.
• The three /api/webhooks/* operator endpoints are described.
• The guide is linked from docs/API.md, docs/README.md, and the README docs index.
• No header/field/env var is mentioned that does not exist in the codebase.

Suggested execution

1. Fork the repo and create a branch — git checkout -b docs/webhook-subscriber-onboarding.
2. Implement changes — add docs/webhook-subscribers.md and update the cross-links in docs/API.md, docs/README.md, and README.md.
3. Write/extend tests — Vitest + Supertest; this is documentation, so no source tests are required, but run npm run validate:spec to confirm the OpenAPI doc still parses if you touch it.
4. Test and commit —

npm run validate:spec
npm run lint
npm test

Example commit message

docs(webhooks): add subscriber onboarding guide with HMAC verification sample

Guidelines

This is a documentation change, so the 95% coverage threshold enforced in CI (vitest.config.ts, via npm run test:coverage) is unaffected, but do not regress it; verify the code samples against src/services/drawWebhookService.ts before submitting. Timeframe: 96 hours.

[xx7412421-cloud]

I would like to work on this issue. I will keep it documentation-only, verify every payload/header/env-var claim against the existing webhook service and routes, and link the new guide from the requested docs indexes.

[dangelo352]

Submitted PR #246: #246

It adds a dedicated webhook subscriber onboarding guide with Express and Next.js HMAC verification examples, local signed-request testing commands, replay protection, idempotency guidance using data.drawId, and links from the API/security/docs index pages.