Webhooks

Webhook endpoints receive real-time HTTP callbacks when events occur in SpeyBooks. Each endpoint subscribes to specific event types and receives signed payloads for verification.

Security

Every endpoint has a signing secret (whsec_...) used to compute an HMAC-SHA256 signature on each delivery payload. Verify the X-SpeyBooks-Signature header against the payload to ensure authenticity. Secrets can be rotated without downtime.

Events

Available event types:

invoice.created, invoice.sent, invoice.paid, invoice.cancelled
payment.received

Delivery

Deliveries are attempted with automatic retries on failure. The delivery log tracks each attempt including response status, duration, and success/failure state.

Limits

Maximum 5 webhook endpoints per organisation
Each endpoint must subscribe to at least one event
URLs must be valid HTTPS endpoints (max 2048 characters)

→ The Webhooks object

Endpoints

GEThttps://app.speybooks.com/api/v1/webhooks/List webhook endpoints POSThttps://app.speybooks.com/api/v1/webhooks/Create webhook endpoint PATCHhttps://app.speybooks.com/api/v1/webhooks/{id}Update webhook endpoint DELETEhttps://app.speybooks.com/api/v1/webhooks/{id}Delete webhook endpoint GEThttps://app.speybooks.com/api/v1/webhooks/{id}/deliveriesWebhook delivery log POSThttps://app.speybooks.com/api/v1/webhooks/{id}/rotateRotate webhook signing secret

Endpoints

GET/v1/webhooks/POST/v1/webhooks/PATCH/v1/webhooks/{id}DELETE/v1/webhooks/{id}GET/v1/webhooks/{id}/deliveries POST/v1/webhooks/{id}/rotate

The Webhooks Objectjson

{
  "id": 3,
  "url": "https://example.com/webhooks/speybooks",
  "description": "Production webhook handler",
  "secretHint": "f6a1",
  "events": [
    "invoice.created",
    "invoice.paid",
    "payment.received"
  ],
  "isActive": true,
  "stats24h": {
    "total": 15,
    "delivered": 14,
    "failed": 1
  }
}