v5.65.0 14 June 2026 Feature

Outbound Webhooks: Real-Time Event Delivery

Why This Matters

Until now the only way to learn that an invoice was issued or a payment landed was to poll the API and diff the result. That is wasteful for integrators and slow for anything that needs to react promptly. Outbound webhooks invert this: SpeyBooks now tells you when something happens, as it happens.

The design decision that matters is where the event is raised. Each event is emitted inside the same database transaction that performs the state change, so an event exists if and only if the change it describes actually committed. There is no separate publish step that can fire on a write that later rolled back, and none that can be silently skipped on a write that succeeded. Delivery to your endpoint is best effort with retries, but the existence of the event is bound to the truth of the ledger.

Outbound Webhooks

Endpoints

  • Configure and manage endpoints Register one or more endpoint URLs in Developer Settings, choose which events each one subscribes to, and activate or deactivate them without losing their delivery history.

  • Signed payloads Every delivery is signed with a per-endpoint secret so your receiver can verify it came from SpeyBooks. The secret can be rotated at any time with no downtime.

  • Internal-address protection Endpoint URLs are validated before they are accepted, so deliveries cannot be aimed at internal or loopback addresses.

Events

  • Five lifecycle events invoice.created, invoice.sent, invoice.paid, invoice.cancelled, and payment.received are now emitted live across the invoice and payment flows.

  • Emitted from within the transaction Each event is raised inside the mutation’s own transaction and fires exactly once per genuine state transition, scoped to sales documents. (AX-WHK-EMIT-001, Class M.)

  • Stable envelope Every event carries a consistent shape: a unique event id, the event type, an ISO timestamp, and a typed data object describing the affected record.

  • Single source of truth for the catalogue The set of valid event types is defined in one place and shared by the API and the documentation, so the wire, the validator, and the docs can never disagree. (AX-WHK-CAT-001, Class M.)

Delivery

  • Retrying background worker A worker delivers each event by signed POST, retries on timeouts and transient server errors, and stops retrying on client rejections that will not succeed on a repeat. Every attempt is recorded with its response status.

  • Visible delivery history Recent deliveries, their status, and the response received are shown per endpoint in Developer Settings, so a failing receiver is obvious rather than silent.

Operational Impact

  • An event is present if and only if its underlying state change committed. No phantom events, and none missed.
  • Each transition produces exactly one event, fanned out to every endpoint subscribed to it.
  • Payloads are signed, and secrets rotate without interrupting delivery.
  • Endpoint URLs cannot target internal addresses.
  • Every delivery attempt and its response status are visible without leaving the product.

Versioning

This release advances the axiom registry from 2.22 to 2.23 and adds two mechanically enforced invariants:

  • AX-WHK-CAT-001: the webhook event catalogue has a single authoritative source. Class M.
  • AX-WHK-EMIT-001: events are wrapped in the canonical envelope once and fanned out per subscribed endpoint. Class M.

The deploy axiom coverage gate moved from 50 to 52 Class M axioms verified. No public API surface was removed or changed; the release is additive.

Files Changed

Backend:

  • Webhook delivery worker and delivery store (migration 105).
  • Event emission wired into the invoice and payment lifecycle mutations.
  • Single-sourced event catalogue feeding both the API and the documentation.

Frontend:

  • Developer Settings: endpoint management, secret rotation, and delivery history including response bodies.

Docs site:

  • Webhooks guide on docs.speybooks.com: per-event payload tables, and the integrations surface marked live and signed rather than planned.

Known Issues

  • Event coverage is currently the five invoice and payment lifecycle events. Coverage of further resources such as contacts, bills, and transactions will follow in later releases.

Webhooks turn SpeyBooks from a system you query into one that tells you when the books change, and the event catalogue is built to grow.