AUTOMATE NOW
  • Connection guide
  • Xero
  • HexaSync

Get started with Xero on HexaSync

Connect Xero to HexaSync through a Xero App (an OAuth 2.0 app created on the Xero Developer Portal), verify the Webhook and create a Xero Connector.

HexaSync TeamLast updated

This guide explains how to connect Xero to HexaSync: you create a Xero Connector by authorizing the connection through a Xero App. When you finish, you can get Contacts, Invoices, Invoice Lines, Items, Accounts and Payments data from Xero into HexaSync to use and integrate that data.

In the default configuration, the Xero Connector only reads data and does not change data in Xero. If you need to write data to Xero, the HexaSync team will advise you in detail during implementation.

Before you start

Note: Each Xero App can be used to connect only one Xero Organisation on HexaSync.

Part 1: Connect Xero to HexaSync

Step 1: Sign in to HexaSync

Step 2: Start authenticating the Xero App on HexaSync

  1. Open the Xero connection setup page on HexaSync.
  2. Continue with the Xero Connector setup flow shown on HexaSync.

Step 3: Provide the Xero App details

  1. If HexaSync shows an app choice, select I will provide my Xero app.
  2. Enter the details from this table:
Field Value to enter
Client ID The Client ID copied from the Xero App (Step 2 of the Create a Xero App guide)
Client Secret The Client Secret of the same Xero App
Webhooks Key The Webhooks Key from the Webhooks section of the same Xero App (Step 3 of the Create a Xero App guide)
  1. Select Continue.
  2. Select Continue to Xero to go to the Xero authorization page.

Note: All three details must belong to the same Xero App. Do not use details from different Apps.

Step 4: Authorize access to the Xero Organisation

  1. Sign in to Xero if asked.
  2. Select exactly one Xero Organisation to connect.
  3. Check the data scopes shown on the authorization page:
    • Contacts
    • Organisation settings
    • Invoices and related documents
    • Payments
  4. Select Allow access to authorize the app.

Note: Select only one Xero Organisation for each connection. If you select several Organisations, HexaSync reports an error and you have to connect again.

Step 5: Set up the official Webhook URL

After Xero grants access, you are returned to HexaSync. The system shows the official Webhook URL for this connection.

  1. Copy the Webhook URL shown by HexaSync.
  2. Go back to the Xero Developer Portal.
  3. Open the Xero App you used for the connection.
  4. Select Webhooks.
  5. Update the configuration:
    • Delivery URL: replace the temporary URL https://app.hexasync.com/webhook with the official Webhook URL you just copied from HexaSync.
    • Events: keep Contacts and Invoices.
  6. Select Save.
  7. Select Send “Intent to receive”.
  8. Wait until the Webhook status shows OK.

The official Webhook URL has the format shown in this example:

https://gateway.hexasync.com/api/v3/messages/your-webhook-url-is-shown-here/

Note:

  • The address above only illustrates the URL format. You must copy the actual Webhook URL that HexaSync provides for your connection, not the example URL.
  • If the status does not change to OK, check that the Delivery URL is entered correctly and verify again. If it still fails, contact support@beehexa.com and attach a screenshot of the error. Do not continue creating the Connector until the Webhook is verified.

Step 6: Finish the Xero connection

  1. Go back to HexaSync.
  2. Select I have saved the webhook URL — continue.
  3. Check that Xero shows the Connected status.
  4. Select Create Xero Connector.

Step 7: Create the Xero Connector

  1. Check the Connector name that HexaSync suggests, for example [Acme Trading Ltd] Xero Connector.
  2. Edit the name if needed so the connected Xero Organisation is easy to recognize.
  3. Select Continue.
  4. Wait for HexaSync to finish creating the Connector.

When it finishes, you are taken to the new Xero Connector in Connector Apps. Check the connection as described in Part 3.

Part 2: Re-authorize the Xero Connector

Re-authorize when HexaSync can no longer access Xero data, for example when the app has been disconnected in Xero or the Connector shows a connection error.

Step 1: Open Settings in the Xero Connector

  1. Open Connector Apps and select the Xero Connector you want to re-authorize. Select Settings in the left menu.
  2. In Integration Apps & Credentials, select Re-authorize on the Xero row.

Cannot use Re-authorize? Only the creator or an admin of the Xero Connector App can see the Re-authorize button. Contact the creator or an admin of the Connector App.

Step 2: Re-authorize on Xero

  1. Sign in to Xero if asked.
  2. Select the Xero Organisation that is linked to the Connector.
  3. Select Allow access.

HexaSync reuses the saved Xero App details. In a normal re-authorization, you do not need to enter the Client ID, Client Secret or Webhooks Key again.

Step 3: Check the Webhook

  1. Check the Webhook status on the Xero Developer Portal.
  2. If the Webhook still has the OK status, go back to HexaSync and select I have saved the webhook URL — continue.
  3. If the Webhook does not have the OK status, check the Delivery URL again as described in Step 5 of Part 1 and verify again.

Note: If the Webhook of the Xero App on the Xero Developer Portal still does not show the OK status after you check the Delivery URL and verify again, contact support@beehexa.com and attach a screenshot of the error. Do not select I have saved the webhook URL — continue until the Webhook is verified.

Step 4: Check the connection

  1. Confirm that Xero shows the Connected status.
  2. Check that the Connector keeps getting data from Xero as described in Part 3.

Data that was already retrieved is kept after you re-authorize.

Part 3: Check that the connection works

Open Connector Apps and select the Xero Connector you just created.

Check the connection details

  • In Settings, under Integration Apps & Credentials, Xero shows the Connected status.
  • Check that it is the Xero Organisation you want to connect.
  • On the Xero Developer Portal, the Webhook of the Xero App has the OK status.

Check the data

  1. Check that the Connector has the six default tasks:
    • Contacts
    • Invoices
    • Invoice Lines
    • Items
    • Accounts
    • Payments
  2. On the first run, HexaSync gets all existing data within the authorized scope.
  3. After that, the data is refreshed every 15 minutes. Changes to Contacts and Invoices are updated in near real time through the Webhook when the Webhook status is OK.

Note: By default, the Xero Connector only reads data from Xero.

Part 4: Common errors and how to fix them

Message How to fix it
Invalid redirect_uri Check the OAuth 2.0 redirect URI in Configuration in the Xero App, as described in Step 1 of the Create a Xero App guide.
You selected more than one organisation Connect again and select only one Xero Organisation.
This Xero app is already connected to several organisations Disconnect the existing Xero connection before you connect to another Organisation.
Xero returned no organisation for this approval Check the Xero account and the Organisation selected during authorization.
Xero rejected the Client ID or Client Secret Check the details in Configuration in the Xero App again, as described in Step 2 of the Create a Xero App guide.
Xero did not accept the authorization Check the OAuth 2.0 redirect URI and go through the authorization again.
HexaSync Could Not Register Your Xero App Check the Client ID, Client Secret and Webhooks Key.
Your Webhook URL Is Not Ready Yet Wait about 30 seconds and select Try again.
We Could Not Get Your Webhook URL Contact support@beehexa.com and provide the error code shown.
The provider did not grant the authorization Select Resume the installation and authorize with Allow access.
We Could Not Find Your Installation Details Start the connection again from HexaSync.
The name already exists Choose a different Xero Connector name.
You’ve reached your app limit Contact support@beehexa.com or delete a Connector App you no longer use.

For other cases, send a screenshot of the error message (with sensitive information hidden) to support@beehexa.com.

Part 5: Frequently asked questions

After Xero is connected, what data does HexaSync get and how often is it updated?

By default, the Xero Connector gets data through six tasks: Contacts, Invoices, Invoice Lines, Items, Accounts and Payments. The first time, HexaSync gets all existing data within the authorized scope. After that, the data is refreshed every 15 minutes. Changes to Contacts and Invoices are updated in near real time through the Webhook when the Webhook status is OK.

Can I continue the connection if the Webhook does not show the OK status yet?

No. You must verify the Webhook before you continue. Check that the Delivery URL has been replaced with the official Webhook URL that HexaSync provides, select Save, then select Send “Intent to receive” as described in Step 5 of Part 1. If the status still does not change to OK, contact support@beehexa.com and attach a screenshot of the error.

Do I need to create the Xero Connector again when access to Xero expires?

No. You can re-authorize the existing Xero Connector as described in Part 2: open Settings, find Integration Apps & Credentials and select Re-authorize. HexaSync reuses the saved Xero App details and keeps the data it already retrieved.

Does HexaSync write or change data in Xero?

No. In the default configuration, the Xero Connector App only reads data and does not write or change data in Xero. If you need to write data to Xero, the HexaSync team will advise you in detail during implementation.