Eve library

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

Guide

Revision 1

On this page

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