Webhooks

Webhooks deliver real-time notifications to your HTTP endpoints when events occur in Kaplaix. Each webhook is HMAC-SHA256 signed for integrity verification.

Notification channels

A notification channel defines a webhook destination. Each channel has:

A URL (must be publicly reachable — private IPs are rejected)
A secret for HMAC signature verification (shown once at creation)
Event filters to control which events trigger notifications

POST/v1/notification-channels

Create a notification channel. Returns the plaintext secret once — store it securely.

Request body:

Field	Type	Required	Description
`name`	string	Yes	Channel display name
`url`	string	Yes	Webhook endpoint URL (must be public)
`events`	string[]	No	Event types to subscribe to

The secret is only returned at creation. If lost, rotate it using the rotate-secret endpoint.

SSRF protection: URLs pointing to private IP ranges (RFC 1918, loopback, link-local, CGNAT, IPv6 ULA, AWS/GCP/Azure metadata endpoints) are rejected.

GET/v1/notification-channels

List all notification channels.

GET/v1/notification-channels/:id

Get channel details.

PATCH/v1/notification-channels/:id

Update channel name, URL, events, or status.

DELETE/v1/notification-channels/:id

Delete a notification channel.

POST/v1/notification-channels/:id/rotate-secret

Rotate the HMAC secret. Returns the new plaintext secret once.

POST/v1/notification-channels/:id/test

Send a synthetic test notification to verify your endpoint.

Verifying webhook signatures

See the Webhook Signature Verification guide for implementation details.