Date: 2026-02-24
Owner: @oshun/isis-team
Checklist: WS10-007
Ticket: ISIS2-00115
Objective#
Add first-class signed callback verification and replay protection controls for outbound webhook events so external orchestrators can authenticate callback origin and reject duplicate/replayed deliveries.
Existing Implementations Reviewed#
Before implementation, these in-repo implementations were analyzed:
apps/isis/generation-api/src/routes/provider-callbacks.ts- existing HMAC-SHA256 verification, hex signature parsing, and constant-time comparison patterns.
apps/isis/generation-api/src/routes/webhook-subscriptions.ts- existing webhook discovery/auth/RBAC route structure and validator patterns.
libs/isis/client/src/resources/generation.ts- typed webhook subscription SDK surface used for parity extensions.
Design decisions from this analysis:
- use HMAC-SHA256 and constant-time comparison for callback signatures,
- enforce versioned signature format (
v1=<hex>), - include timestamp + nonce in signature content to prevent replay,
- expose callback security metadata via event-type discovery for integrators,
- provide typed sign/verify APIs with RBAC and OpenAPI/SDK parity.
Delivered API Surface#
Added callback security endpoints:
POST /api/v1/webhook-subscriptions/callback-security/signPOST /api/v1/webhook-subscriptions/callback-security/verify
Enhanced existing webhook event-type discovery:
GET /api/v1/webhook-subscriptions/event-types- now includes callback signing/verification header and algorithm metadata.
Security Model#
- Signature algorithm:
HMAC-SHA256 - Signature version:
v1 - Signed payload format:
X-Isis-Webhook-Timestamp.X-Isis-Webhook-Nonce.<raw-payload>
- Required verification inputs:
- payload, signing secret, signature, timestamp
- Optional replay dimensions:
- nonce + eventId
- Replay protection:
- nonce/signature-based replay cache with tolerance-window TTL
SDK Parity#
@isis/client GenerationResource now includes:
signWebhookCallback(request)verifyWebhookCallback(request)
Typed SDK contracts now include callback security spec/sign/verify request and response types, plus event-type discovery metadata for callback security.
Verification Commands#
bash
pnpm --filter @isis/generation-api exec vitest run src/services/webhook-callback-security.service.spec.ts src/routes/webhook-subscriptions.spec.ts src/app.auth.spec.ts src/openapi.contract.spec.ts --reporter=dot
pnpm --filter @isis/client exec vitest run src/resources/generation.webhook-subscriptions.route-parity.spec.ts --reporter=dot
node scripts/isis/generate_generation_api_openapi.mjs --check
pnpm --filter @isis/generation-api run openapi:check