Skip to content

PRD-21: Webhook / Event Notification System #14

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)

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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