# ISIS v2 Webhook Callback Signature Verification and Replay Protection (WS10-007)

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/sign`
- `POST /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
```
