Webhooks

A webhook is a request Saasybill sends to a URL you choose when something changes. Use webhooks to learn that an invoice was paid or a subscription ended, instead of polling the API.

Events

Every event and what its payload holds.

Verify signatures

Check each request came from Saasybill.

Delivery and retries

What happens when your server is down.

Set up an endpoint

Endpoints are managed in the app. The API doesn’t manage them yet. Only an owner or admin can add one.

Open Webhooks

Go to Organisation Settings, then Developer Settings, then Webhooks.

Add the endpoint

Click Add Endpoint and fill in the fields.

Field	Description
Endpoint URL	Where Saasybill sends events, such as `https://example.com/saasybill-webhooks`.
Description	A note for you, such as `Billing sync`. Up to 255 characters.
Events	All events, including any added later, or a chosen list.

Copy the signing secret

Click Add Endpoint. The Your Signing Secret dialog shows a secret beginning whsec_. Copy it now and store it as an environment variable. It can’t be shown again.

Send a test event

Open the endpoint’s menu and click Send Test Event. Confirm your server receives it and passes signature verification.

Endpoint rules

Rule	Detail
Protocol	`https://` only.
Port	443 only.
Address	Must be reachable from the internet. Addresses such as `localhost`, private networks and link-local ranges are refused.
URL	No username or password, and no `#` fragment. Up to 2,000 characters.
Redirects	Not followed. A `3xx` response counts as a failure.
Limit	Up to 10 endpoints per organisation.

The address is checked when you save the URL and again on every delivery.

To receive webhooks while developing on your own machine, use a tunnelling tool that gives you a public https:// address.

Manage an endpoint

Each endpoint has a menu.

Action	What it does
Edit Endpoint	Change the URL, description or events.
Send Test Event	Sends a `webhook.test` event. Only on an active endpoint.
Roll Secret	Issues a new signing secret. The old one keeps signing for 24 hours.
Turn Off / Turn On	Pause or resume delivery.
Delete Endpoint	Stops events and deletes the delivery history.

What a webhook looks like

Saasybill sends a POST with a JSON body.

POST /saasybill-webhooks HTTP/1.1
Content-Type: application/json
User-Agent: Saasybill-Webhooks/1
Saasybill-Signature: t=1790741520,v1=9c1e4f7a2b8d3065e1a7c94b0d2f83e6a5b1c7d90e4f2a86b3d5c1e07f9a4b28
Saasybill-Event-Id: evt_6c3f0b9e2a7d4f1c8e5a9b0d3c2f1e47
Saasybill-Delivery-Id: 4e8b1a7c-2d95-4f06-b3a8-9c1e7d5f0a62
Saasybill-Delivery-Attempt: 1

{
  "id": "evt_6c3f0b9e2a7d4f1c8e5a9b0d3c2f1e47",
  "object": "event",
  "type": "invoice.paid",
  "created": "2026-10-04T04:12:00.000Z",
  "livemode": true,
  "data": {
    "object": {
      "id": "5f8a3c9d-7e21-4b04-9c6d-0a2b4e8f1d55",
      "object": "invoice",
      "status": "paid",
      "customer": "3b9f1c1e-6a52-4c0e-9d7e-1f6f2f0b7a11",
      "subscription": "9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33",
      "number": "INV-0042",
      "total": "613.8000",
      "xero_sync_status": "synced"
    },
    "previous_attributes": {
      "status": "approved"
    }
  }
}

Header	Description
`Saasybill-Signature`	The signature you verify.
`Saasybill-Event-Id`	The event’s id, the same as `id` in the body. Use it to skip repeats.
`Saasybill-Delivery-Id`	The id of this delivery of the event.
`Saasybill-Delivery-Attempt`	Which attempt this is, starting at 1.
`User-Agent`	`Saasybill-Webhooks/1`.

The event object

Field	Description
`id`	The event id, beginning `evt_`.
`object`	Always `event`.
`type`	What happened, such as `invoice.paid`. See Events.
`created`	When Saasybill recorded the event.
`livemode`	`true` for a live organisation.
`data.object`	The object the event is about: its `id`, `object` type and the tracked fields.
`data.previous_attributes`	The previous value of each tracked field that changed. Absent on `created`, `deleted` and test events.

Events are thin on purpose. They carry the fields that changed and no more. To get the full object, fetch it with its id, for example GET /v1/invoices/{id}.

Respond quickly

Reply with any 2xx status within 10 seconds. Acknowledge the event first and do the slow work afterwards, on a queue or a background job. Anything else is a failure and is retried.

Things to know

Events can arrive up to a minute late

Saasybill finds changes about once a minute by comparing each object with how it looked last time. An event arrives up to a minute after the change.

Changes inside one minute are combined

An invoice that is approved and paid within the same minute arrives as one invoice.paid event, and previous_attributes.status is draft. You won’t see an approved step. Write your handler to depend on the current state, not on seeing every step.

Events can arrive more than once

Delivery is at-least-once. Store each Saasybill-Event-Id you have processed and skip repeats.

Events can arrive out of order

Order is not guaranteed, and a retry can arrive after a newer event. If order matters, fetch the object from the API and act on its current state.

A new endpoint doesn't announce what already exists

When an organisation gets its first endpoint, Saasybill records the current state silently. You’ll hear about changes from then on, not about every existing invoice.

Only customers are announced, not every contact

A Xero contact that hasn’t been imported as a customer produces no events until it is imported.

Getting started

Fundamentals

Integration guides

Organisation

Customers

Plans

Charges

Subscriptions

Invoices

Webhooks

Events

Verify signatures

Delivery and retries

Set up an endpoint

Endpoint rules

Manage an endpoint

What a webhook looks like

The event object

Respond quickly

Things to know

Events

Verify signatures

Delivery and retries

​Set up an endpoint

​Endpoint rules

​Manage an endpoint

​What a webhook looks like

​The event object

​Respond quickly

​Things to know

Set up an endpoint

Endpoint rules

Manage an endpoint

What a webhook looks like

The event object

Respond quickly

Things to know