Prerequisites
The connector should already be set up, with a Connector Profile and a Linked Account. See Getting Started on the Xero connector page.Retrieve the StackOne Native Webhook URL
The Native Webhook URL is generated once a Xero account has been linked in StackOne. Each linked account has its own URL.
- Open the linked account in StackOne.
- Copy the value from Native Webhook URL.
Create the webhook in your Xero app
Add the Native Webhook URL to the Xero app used by the connector profile, so Xero posts events to StackOne.
Open the app's webhook settings
Sign in to the Xero Developer portal and open My Apps.
- Select the app whose Client ID is set on the StackOne connector profile.
- In the left menu, click Webhooks.
Choose the events and save
Under Notify this app about changes to, tick the categories you want to receive.
- Tick any of Contacts, Invoices, Credit notes, Prepayments and Overpayments.
- Paste the Native Webhook URL into Delivery URL.
- Click Save. Xero then shows the Webhooks key and the status ‘Intent to receive’ required.
Add the Webhooks key and confirm delivery
Xero only delivers events after StackOne passes its Intent to receive check, which needs the Webhooks key on the linked account.
Add the Webhooks key to the linked account
Copy the Webhooks key from the Xero app’s Webhooks page.
- In StackOne, edit the linked Xero account and paste the key into Webhooks Key.
Send Intent to receive
Back on the Xero app’s Webhooks page, click Send ‘Intent to receive’.
- The status changes to OK within about 30 seconds.
- If it stays at ‘Intent to receive’ required, check that the Webhooks Key on the account matches the key shown in Xero and that the Delivery URL is the account’s Native Webhook URL.
Available webhook events
Each event’s record ID is the Xero ID of the affected record (resourceId). Xero sends only
identifiers, so fetch the record for its current state.
Contact events
Events for contacts.
- Contact Created (
contact.created) — A new contact was created. - Contact Updated (
contact.updated) — An existing contact was updated, including being archived.
Invoice events
Events for sales invoices and bills.
- Invoice Created (
invoice.created) — A new invoice or bill was created. - Invoice Updated (
invoice.updated) — An existing invoice or bill was updated, including being approved, paid, voided or deleted.
Credit note events
Events for credit notes.
- Credit Note Created (
creditnote.created) — A new credit note was created. - Credit Note Updated (
creditnote.updated) — An existing credit note was updated, including allocations, refunds and voids.
Prepayment and overpayment events
Events for prepayments and overpayments.
- Prepayment Created (
prepayment.created) — A new prepayment was created. - Prepayment Updated (
prepayment.updated) — An existing prepayment was updated, for example allocated, refunded or voided. - Overpayment Created (
overpayment.created) — A new overpayment was created. - Overpayment Updated (
overpayment.updated) — An existing overpayment was updated, for example allocated, refunded or voided.
Delivery format
Details of how Xero delivers events to StackOne.
Batched payloads
Each request carries an events array and can contain several events of different categories. StackOne splits every request and routes each event on its own by its eventCategory and eventType. The event data is that single Xero event, with resourceId, resourceUrl, eventDateUtc and tenantId.
Signatures and retries
Xero signs each request with a base64 HMAC SHA256 digest in the x-xero-signature header, keyed with the Webhooks key. StackOne verifies it during Intent to receive. Xero retries failed deliveries and disables the webhook after 24 hours of failures, which puts it back to ‘Intent to receive’ required.