Skip to content

PRD-21: Webhook / Event Notification System #14

@PancheI

Description

@PancheI

Add HMAC-signed webhook delivery for signing, policy violation, and lifecycle events with retry logic, auto-disable, and delivery logging.

Acceptance Criteria

  • webhooks and webhook_deliveries tables created with RLS policies
  • POST /signers/:id/webhooks creates a webhook and returns the HMAC secret exactly once
  • GET /signers/:id/webhooks lists only the authenticated owner's webhooks (no secret in response)
  • DELETE /signers/:id/webhooks/:webhookId removes the webhook and all delivery logs
  • POST /signers/:id/webhooks/:webhookId/test delivers a test event
  • Successful signing triggers signing.completed event
  • Policy violation triggers policy.violated event
  • Signer lifecycle events trigger corresponding events
  • Payload includes X-Guardian-Signature header with valid HMAC-SHA256
  • Failed deliveries retried 3 times with exponential backoff (1s, 5s, 25s)
  • HTTP 4xx responses are not retried
  • Webhooks auto-disabled after 10 consecutive failures
  • consecutive_failures resets on successful delivery
  • Webhook secrets stored as SHA-256 hashes, never plaintext
  • Webhook URLs validated (HTTPS in production, HTTP in dev)

Tasks

  • Database migration: webhooks + webhook_deliveries tables
  • Install @nestjs/event-emitter, add EventEmitterModule
  • WebhookRepository, WebhookService, WebhookController
  • WebhookEventService (event emitter wrapper)
  • WebhookDeliveryService (HMAC, delivery, retry logic)
  • Integrate event emission into InteractiveSignService and SignerService
  • Unit + integration tests
  • Dashboard UI: webhook management on signer detail page (optional)

Metadata

Metadata

Assignees

No one assigned

    Labels

    P1High priorityphase-2Go-live minimumprdProduct requirement document

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions