Skip to main content
Main content start

Introducing Prepayments webhooks: a more efficient way to sync data

Prepayments webhooks are now generally available, giving Xero developers a faster and more efficient way to keep integrations up to date when prepayments change.

For a long time, many integrations have relied on scheduled API polling to detect changes in accounting data. Polling works but it adds unnecessary load, introduces latency, and becomes harder to manage as your customer base grows.

With Prepayments webhooks, your integration can listen for changes and respond when something happens instead of repeatedly asking whether anything has changed.

What’s the problem we’re solving?

Prepayments are an important part of the accounting workflow. They help businesses record money received or paid before it is allocated to an invoice or bill, and their status can change as the transaction moves through its lifecycle.

Until now, the main way to stay up to date was to poll the Accounting API on a schedule, even when there was nothing new to process. That approach can:

  • Add unnecessary load to your infrastructure and Xero’s

  • Increase the time between a change happening in Xero and your app reflecting it

  • Require additional API calls just to determine whether an event is relevant

  • Become more expensive and difficult to scale as transaction volume increases

Prepayments webhooks give you another option. Your app can subscribe to prepayment events and process them as they arrive, helping you build more responsive and efficient workflows.

What’s included?

Prepayments webhooks notify your app when a prepayment is created or updated in Xero. They use the same webhook configuration and delivery pattern as other Xero webhooks, so you can extend an existing implementation without learning a new integration model.

Each event includes the standard webhook envelope fields, including:

  • resourceUrl — the URL of the prepayment resource that changed

  • resourceId — the ID of the prepayment resource that changed

  • eventDateUtc — when the event occurred

  • eventType — CREATE or UPDATE

  • eventCategory — PREPAYMENT

  • tenantId — the Xero organisation associated with the event

  • tenantType — ORGANISATION

The payload also includes prepayment-specific fields:

  • data.Type — for example, RECEIVE-PREPAYMENT or SPEND-PREPAYMENT

  • data.Status — for example, AUTHORISED, PAID, or VOIDED

  • data.UpdatedDateUTCString — the latest updated date and time in ISO 8601 format

Here is an example payload:

{ "events": [ { "resourceUrl": "https://api.xero.com/api.xro/2.0/Prepayments/717f2bfc-c6d4-41fd-b238-3f2f0c0cf777", "resourceId": "717f2bfc-c6d4-41fd-b238-3f2f0c0cf777", "eventDateUtc": "2025-10-21T01:15:39.902", "eventType": "UPDATE", "eventCategory": "PREPAYMENT", "tenantId": "c2cc9b6e-9458-4c7d-93cc-f02b81b0594f", "tenantType": "ORGANISATION", "data": { "Type": "RECEIVE-PREPAYMENT", "Status": "PAID", "UpdatedDateUTCString": "2025-10-21T01:15:39Z" } } ] }

The resourceUrl and resourceId let you retrieve the full prepayment resource when your integration needs additional fields beyond the webhook payload.

Build more selective integrations

Getting a notification is only part of the story. Your app also needs enough context to decide what to do next.

The prepayment type and status are included directly in the payload, so your webhook handler can inspect an event before making a follow-up API call. For example, you can:

  • Route receive and spend prepayments to different workflows

  • Trigger actions only when a prepayment reaches a relevant status

  • Ignore events that do not apply to your integration

  • Retrieve the full resource only when additional detail is required

  • Keep downstream systems aligned with changes in Xero

This gives you more control over how your integration processes events and helps reduce unnecessary API traffic.

What can you build?

Prepayments webhooks can support a range of integration patterns, including:

  • Synchronising prepayment records into an external accounting, reporting, or reconciliation system

  • Updating internal workflows when a prepayment is created, paid, or voided

  • Keeping customer-facing dashboards and operational tools current

  • Triggering notifications or review workflows for specific prepayment statuses

  • Reducing polling for integrations that need timely updates across many organisations

The right implementation will depend on your workflow, but the core pattern is the same: subscribe to the event, verify and accept the notification, inspect the payload, and retrieve the full resource when needed.

Getting started

If you already use Xero webhooks, you can add Prepayments events to your existing configuration.

  1. Open your app in the Xero Developer Portal and navigate to your Webhooks configuration.

  2. Add a subscription for Prepayment events.

  3. Update your webhook handler to:

  • Verify the webhook signature

  • Respond quickly with a 2xx status

  • Inspect the event type, prepayment type, status, and updated date

  • Decide whether to retrieve the full prepayment resource using resourceUrl or resourceId

  • Log and monitor events so you can compare observed behaviour with your expectations

You can find the full event schema, payload examples, and implementation guidance in the Xero webhooks documentation. The complete contract is also available in the Xero OpenAPI specification.

A more reactive Xero ecosystem

Prepayments webhooks are part of our broader work to expand event coverage across the Xero platform and give developers better alternatives to polling.By making more accounting events available through webhooks, you can build integrations that are more responsive, more selective about the data they process, and easier to scale as your customers growWe’re looking forward to seeing how you use Prepayments webhooks to build better experiences for your customers.