Webhook events

Twelve events cover customers, subscriptions and invoices. Choose the ones you need when you add an endpoint.

Event types

Event	Fires when
`customer.created`	A customer is added, including one imported from Xero.
`customer.updated`	A customer’s code, name, email or status changes.
`customer.deleted`	A customer is removed.
`subscription.created`	A subscription is created.
`subscription.updated`	Units, plan, renewal date, discount or label changes, or cancel at period end is switched. This includes each renewal.
`subscription.ended`	A subscription ends or completes.
`subscription.deleted`	A subscription is deleted.
`invoice.created`	An invoice is raised.
`invoice.updated`	An invoice’s total, number, status or Xero sync changes.
`invoice.paid`	An invoice is paid.
`invoice.voided`	An invoice is voided.
`invoice.deleted`	An invoice is deleted.

There’s also webhook.test, sent by Send Test Event. You can’t subscribe to it.

Tracked fields

An event’s data.object holds these fields and no others. Only a change to one of them creates an updated event. A change to any other field is not announced, which stops a busy subscription announcing itself every minute. Every data.object also has id and object.

Customer
Subscription
Invoice

Field	Description
`code`	The customer’s code.
`name`	The customer’s display name.
`email`	The customer’s email.
`status`	`active` or `inactive`.

Field	Description
`status`	`pending`, `active`, `complete` or `ended`.
`customer`	The customer’s id.
`plan`	The plan’s id.
`units`	The current units.
`renewal_date`	The next renewal date, `YYYY-MM-DD`.
`discount_percent`	The discount, such as `"10.00"`.
`label`	The subscription’s label.
`cancel_at_period_end`	`true` when set to end at its renewal date.

Field	Description
`status`	The invoice’s status.
`customer`	The customer’s id.
`subscription`	The subscription’s id, or `null`.
`number`	Xero’s invoice number, or `null`.
`total`	The invoice total, such as `"613.8000"`.
`xero_sync_status`	`synced`, `pending` or `failed`.

These are the same values the API returns, in the same formats. data.object is a summary, not the full object. Fetch the full object with GET /v1/{customers|subscriptions|invoices}/{id}.

How the events relate

created has no previous_attributes.
updated carries previous_attributes with the earlier value of each field that changed.
deleted carries the object as it was just before it was deleted.
invoice.paid, invoice.voided and invoice.deleted replace invoice.updated when the status changes to that value. A status change to anything else, or any other tracked change, is invoice.updated.
subscription.ended replaces subscription.updated when the status moves to ended or complete. If other fields change in the same minute, you’ll also get a subscription.updated.
A move between ended and complete isn’t announced.

Example payloads

Customer created

{
  "id": "evt_0f7a3c9e1b2d4e6a8c5b7d9f1a3c5e70",
  "object": "event",
  "type": "customer.created",
  "created": "2026-09-30T04:10:12.000Z",
  "livemode": true,
  "data": {
    "object": {
      "id": "3b9f1c1e-6a52-4c0e-9d7e-1f6f2f0b7a11",
      "object": "customer",
      "code": "ACME-001",
      "name": "Acme Pty Ltd",
      "email": "accounts@acme.example",
      "status": "active"
    }
  }
}

Subscription updated

Units went from 10 to 15.

{
  "id": "evt_9b1d7f3a5c2e4a6c8e0b2d4f6a8c0e12",
  "object": "event",
  "type": "subscription.updated",
  "created": "2026-10-08T01:03:00.000Z",
  "livemode": true,
  "data": {
    "object": {
      "id": "9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33",
      "object": "subscription",
      "status": "active",
      "customer": "3b9f1c1e-6a52-4c0e-9d7e-1f6f2f0b7a11",
      "plan": "b6c1e0a4-2f7d-4a61-8f0c-5d3e9a7b2c44",
      "units": 15,
      "renewal_date": "2026-10-30",
      "discount_percent": "10.00",
      "label": "Acme – Team plan",
      "cancel_at_period_end": false
    },
    "previous_attributes": {
      "units": 10
    }
  }
}

Invoice paid

{
  "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"
    }
  }
}

Invoice failed to sync

An invoice.updated event when Xero refuses an invoice.

{
  "id": "evt_2a4c6e8b0d1f3a5c7e9b1d3f5a7c9e34",
  "object": "event",
  "type": "invoice.updated",
  "created": "2026-09-30T04:12:30.000Z",
  "livemode": true,
  "data": {
    "object": {
      "id": "5f8a3c9d-7e21-4b04-9c6d-0a2b4e8f1d55",
      "object": "invoice",
      "status": "draft",
      "customer": "3b9f1c1e-6a52-4c0e-9d7e-1f6f2f0b7a11",
      "subscription": "9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33",
      "number": null,
      "total": "613.8000",
      "xero_sync_status": "failed"
    },
    "previous_attributes": {
      "xero_sync_status": "pending"
    }
  }
}

Test event

Send Test Event sends an event about no object, so you can check your wiring.

{
  "id": "evt_8e0a2c4f6b1d3a5c7e9f1b3d5a7c9e56",
  "object": "event",
  "type": "webhook.test",
  "created": "2026-09-30T04:15:00.000Z",
  "livemode": true,
  "data": {
    "object": { "id": "test", "object": "test" }
  }
}

Handling events

Verify the signature

Reject anything that fails. See Verify signatures.

Skip repeats

Look up Saasybill-Event-Id. If you have processed it, reply 200 and stop.

Reply straight away

Return 200 before you do slow work.

Fetch the current state

Use data.object.id to fetch the full object from the API, and act on what it is now. This copes with events that arrive late or out of order.

Getting started

Fundamentals

Integration guides

Webhooks

Organisation

Customers

Plans

Charges

Subscriptions

Invoices

Event types

Tracked fields

How the events relate

Example payloads

Customer created

Subscription updated

Invoice paid

Invoice failed to sync

Test event

Handling events

​Event types

​Tracked fields

​How the events relate

​Example payloads

​Customer created

​Subscription updated

​Invoice paid

​Invoice failed to sync

​Test event

​Handling events

Event types

Tracked fields

How the events relate

Example payloads

Customer created

Subscription updated

Invoice paid

Invoice failed to sync

Test event

Handling events