Webhooks

​

What you can configure

• Create, list, update, and delete webhook endpoints.
• Subscribe an endpoint to one or more enabled event types from the catalogue.
• Rotate the signing secret.
• Send a test payload to your endpoint to verify reachability and signature handling.

​

Delivery behaviour

• Live event deliveries use Spotzee-Signature: t=<unix-ts>,v1=<hex-hmac-sha256> with replay protection.
• Test deliveries from the Spotzee UI use X-Spotzee-Signature: sha256=<hex> when the endpoint has a signing secret.
• Failed endpoints may be disabled to prevent repeated delivery attempts to an unreachable URL.

​

Configure an endpoint

• A target URL (must be https://).
• A list of subscribed event types from the catalogue.
• A signing secret (issued on creation; rotate via POST /api/client/webhooks/{endpointId}/rotate-secret).

​

Test a delivery

{
  "event_type": "test.webhook-test",
  "timestamp": "2026-04-30T12:00:00.000Z",
  "project_id": 42,
  "data": {
    "message": "This is a test webhook from Spotzee",
    "webhook_id": 7,
    "webhook_name": "your-endpoint-name"
  }
}

import crypto from 'node:crypto'

export function verifyTestWebhook(rawBody, header, secret) {
  if (!header?.startsWith('sha256=')) return false
  const supplied = header.slice('sha256='.length)
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  const a = Buffer.from(expected, 'hex')
  const b = Buffer.from(supplied, 'hex')
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

​

Rotate the signing secret

​

Reference

• Webhook endpoint CRUD: see the Webhooks tag in the Main API reference.
• Enterprise email event catalogue: see Email delivery event webhooks.

​

Next steps