Webhooks

Receive real-time notifications when events occur in SpeyBooks.

Planned feature

Webhooks are on the roadmap. This documentation describes the planned implementation.

Overview

Webhooks allow you to build integrations that react to events:

• Invoice created, sent, or paid
• Payment received
• Contact created
• VAT return submitted

Event types

Event	Description
invoice.created	New invoice created
invoice.sent	Invoice marked as sent
invoice.paid	Invoice fully paid
invoice.overdue	Invoice past due date
payment.received	Payment recorded
contact.created	New contact added
vat.submitted	VAT return submitted to HMRC

Webhook payload

{
  "id": "evt_abc123",
  "type": "invoice.paid",
  "created_at": "2026-01-31T14:30:00Z",
  "data": {
    "invoice_id": "inv_7k2m9p",
    "amount": 120000,
    "paid_at": "2026-01-31T14:30:00Z"
  }
}

Registering webhooks

curl -X POST https://api.speybooks.com/v1/webhooks \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/speybooks",
    "events": ["invoice.paid", "payment.received"]
  }'

Verification

Webhooks include a signature header for verification:

X-SpeyBooks-Signature: sha256=abc123...

Verify using your webhook secret to ensure requests are genuine.

Retry policy

Failed webhook deliveries are retried:

• 1 minute
• 5 minutes
• 30 minutes
• 2 hours
• 24 hours

After 5 failures, the webhook is disabled.