Webhook Wizard

CaseSolo now has a production-oriented webhook wizard for custom API and automation adapters.

Source Of Truth

• src/lib/webhooks/wizard.ts owns webhook templates, event options, sample payloads, HMAC signing, retry defaults, delivery history normalization, dead-letter classification, and replay payload selection.
• src/app/api/settings/webhooks/route.ts lists and creates firm-scoped webhook endpoints with wizard metadata.
• src/app/api/settings/webhooks/wizard/route.ts exposes admin-only wizard actions for validation previews, signature previews, and failed/dead-letter replay.
• src/app/(dashboard)/settings/webhooks/page.tsx renders templates, endpoint setup, validation preview, test delivery, recent delivery history, and replay controls.

Endpoint Contracts

GET /api/settings/webhooks

• Requires ADMIN or SUPER_ADMIN.
• Returns webhooks, normalized deliveries, wizard templates, supported events, and default retryPolicy.

POST /api/settings/webhooks

• Requires ADMIN or SUPER_ADMIN.
• Creates a WebhookEndpoint for the current firm only.
• Accepts url, events, optional secret, optional templateId, optional retryPolicy, optional description, and optional active.
• Uses a submitted secret when provided; otherwise generates a crypto.randomUUID() secret.
• Stores template, retry, delivery, and dead-letter metadata on the endpoint.

POST /api/settings/webhooks/wizard

• validate_payload: validates a custom payload or generates a sample payload for the selected event. If a secret is supplied, the response includes preview HMAC headers.
• sign_payload: returns a deterministic signature/body preview for a payload and secret.
• replay_delivery: replays only failed or dead-letter deliveries by firm-scoped endpoint lookup, HMAC-signs the replay, appends replay history, resets failure count on success, and writes an immutable audit event.

Security Notes

• Wizard routes are admin-only and tenant-scoped through firmId.
• Replay uses updateMany({ where: { id, firmId } }) after a firm-scoped lookup.
• Browser responses include endpoint secrets because the settings UI currently exposes copy/reveal controls for admins. Do not reuse this pattern for OAuth tokens or third-party provider secrets.
• Custom outbound URLs still need SSRF hardening before expanding this to untrusted public self-service connectors.

Verification

• npm run test:run -- settings-webhooks-wizard: 6/6 tests passing.
• npx tsc --noEmit --pretty false: passing for this worktree snapshot.
• npx eslint src/lib/webhooks/wizard.ts src/app/api/settings/webhooks/route.ts src/app/api/settings/webhooks/wizard/route.ts src/app/'(dashboard)'/settings/webhooks/page.tsx src/__tests__/api/settings-webhooks-wizard.test.ts: passing.