Webhooks

Outbound webhook system with HMAC-SHA256 signing, retry logic, and delivery logging.

Source: src/webhooks/
Permission: MANAGE_NOTIFICATIONS

API Endpoints

Method	Endpoint	Description
POST	/webhooks	Create webhook endpoint
GET	/webhooks	List webhooks
GET	/webhooks/:id	Get webhook details
PATCH	/webhooks/:id	Update webhook
DELETE	/webhooks/:id	Delete webhook
POST	/webhooks/:id/test	Send test payload
POST	/webhooks/:id/regenerate-secret	Regenerate signing secret
GET	/webhooks/:id/history	Delivery history
GET	/webhooks/stats	Delivery statistics

Security

HMAC-SHA256 Signing

Every outbound request includes a signature header:

X-Webhook-Signature: sha256=<hmac_hex_digest>

• Secret auto-generated on creation via crypto.randomBytes()
• Can be regenerated without recreating the webhook
• Consumers verify by computing HMAC of the raw body with the shared secret

Request Configuration

• Timeout: 10 seconds per delivery attempt
• Parallel dispatch: Multiple webhooks triggered concurrently for the same event

Delivery Flow

Event triggered → WebhookService.triggerWebhook(event, payload)
  → Find matching webhook endpoints
    → For each endpoint (parallel):
        → Sign payload with HMAC-SHA256
        → POST to URL with signature header
        → Log result to WebhookLog

Prisma Models

• WebhookEndpoint — URL, secret, subscribed events, enabled flag
• WebhookLog — Delivery attempt records (status, response code, duration)

Related Modules

• EventsModule — Event sources that trigger webhooks
• NotificationsModule — Alternative notification channels