Description:
Build a webhook subsystem where integrators register endpoints and receive HMAC-signed intent/solver events with retries, backoff, and a delivery log.
Problem Statement & Context:
Integrators (wallets, aggregators, DAOs) that cannot hold persistent WebSocket connections must poll. Webhooks are the standard server-to-server integration primitive.
Scope & Acceptance Criteria:
- CRUD for subscriptions (
url, events[], secret), authenticated via API keys.
- Delivery with
X-Vortex-Signature (HMAC-SHA256 over timestamp + body), 5 retries with exponential backoff, auto-disable after sustained failures.
- Delivery log endpoint with replay of a failed delivery.
- SSRF protection on registration and delivery (blocks private IPs, metadata endpoints, redirects).
- Out of scope: per-event filtering expressions.
Implementation Guidelines:
- Key Files/Modules: new
src/webhooks/, src/intents/intents.gateway.ts (event source), prisma/schema.prisma.
- Design/Architecture: Deliveries enqueued via outbox/job queue; workers independent from request path.
- Edge Cases/Constraints: Slow endpoints (timeout 5 s) must not block others; ordering per subscription best-effort with sequence numbers.
- Testing: Signature verification tests; retry/disable lifecycle; SSRF test matrix.
Definition of "Done": Common DoD; integrator docs with verification snippet.
Resources:
Common Definition of "Done" (applies in addition to the criteria above):
- Code written, tested, and documented (TSDoc on public APIs, README/runbook/ADR updates where behaviour changes).
- All acceptance criteria met;
npm run lint, npm run typecheck, npm test, npm run test:e2e pass in CI.
- PR follows
.github/PULL_REQUEST_TEMPLATE, uses a Conventional Commit title (enforced by commitlint), includes test output / metrics screenshots, and references the issue.
- New env vars are added to
.env.example variants and src/config/env.validation.ts (the check:env-drift script must pass).
- Reviewed and approved by at least one CODEOWNER.
Description:
Build a webhook subsystem where integrators register endpoints and receive HMAC-signed intent/solver events with retries, backoff, and a delivery log.
Problem Statement & Context:
Integrators (wallets, aggregators, DAOs) that cannot hold persistent WebSocket connections must poll. Webhooks are the standard server-to-server integration primitive.
Scope & Acceptance Criteria:
url,events[],secret), authenticated via API keys.X-Vortex-Signature(HMAC-SHA256 over timestamp + body), 5 retries with exponential backoff, auto-disable after sustained failures.Implementation Guidelines:
src/webhooks/,src/intents/intents.gateway.ts(event source),prisma/schema.prisma.Definition of "Done": Common DoD; integrator docs with verification snippet.
Resources:
Common Definition of "Done" (applies in addition to the criteria above):
npm run lint,npm run typecheck,npm test,npm run test:e2epass in CI..github/PULL_REQUEST_TEMPLATE, uses a Conventional Commit title (enforced by commitlint), includes test output / metrics screenshots, and references the issue..env.examplevariants andsrc/config/env.validation.ts(thecheck:env-driftscript must pass).