fmAccounting Link (Xero Edition) v2 Webhooks

Webhooks allow you to subscribe to certain events that happen in Xero – currently this is limited to contact and invoice events. When one of these events are triggered Xero will send a HTTP POST payload to the webhook’s configured URL. Webhooks are configured on a per-app basis and Xero will send you events for every Xero organisation connected to the app.

N.B. You can also use Claris Connect Webhooks. If you are a Claris Connect customer you can setup Webhooks in Claris Connect to receive incoming notifications from Xero. This is usually a much simpler process than using the supplied PHP files for the FileMaker Data API as you don't need to worry about hosting the files and dealing with web servers, PHP configuration changes, port forwarding etc. 

Please visit the https://support.databuzz.com.au/article/630-xero-webhooks-using-claris-connect guide for instructions on setting up Claris Connect Webhooks for Xero.

fmAccounting Link (Xero Edition) v2.1 supports Xero webhooks for both the contact and invoice event notifications (you can easily retrofit this into an earlier version or custom integrations as well). You can use the supplied PHP files to setup webhooks for either the FileMaker PHP API or the FileMaker Data API and have changes to contacts and invoices automatically pushed to the fmAccounting Link (Xero Edition) file (or your custom integration).

You’ll find 2 folders in the PHP Webhooks folder containing the php files for both the Data API Webhooks and the PHP API Webhooks:

To use Webhooks with fmAccounting Link (Xero Edition) v2.1 you will need to ensure the following are in place for either the FileMaker Data API or the FileMaker PHP API:

FileMaker Data API

  • your copy of fmAccounting Link must be hosted by FileMaker Server v17 or later
  • you will need to enable the Data API and host the fmAccountingLinkWebhook.php PHP file (either on your FileMaker Server or elsewhere, for example Amazon Lightsail or your own web server running PHP)

FileMaker PHP API

  • your copy of fmAccounting Link must be hosted by FileMaker Server v16 or later
  • you will need to deploy and configure Custom Web Publishing with PHP and host the fmAccountingLinkWebhook.php PHP file (either on your FileMaker Server or elsewhere, for example Amazon Lightsail or your own web server running PHP)
  • If you are using FileMaker Server v17 or later you cannot use the FileMaker Server Admin Console to enable Custom Web Publishing using the PHP API. You will need to use the Command Line Interface to enable these – see the FileMaker Server 17 Help for more information on these commands

For both the FileMaker Data API and the PHP API you will also need the following:

  • the URL needs to begin with HTTPS: Xero only support HTTPS Webhook URLs
  • you need to install the supplied fmAccountingLinkWebhook.php file on your Web Server and determine the URL to this page from the outside. For example if your web server has a domain name of www.myserver.com and you create a folder called XeroWebhooks and place the fmAccountingLinkWebhook.php file inside the XeroWebhooks folder the URL will be: https://www.myserver.com/XeroWebhooks/fmAccountingLinkWebhook.php

If you’re not sure about what the external URL to the fmAccountingLinkWebhook.php file is talk to your IT person – they may need to setup port forwarding on your Internet router in some cases.

N.B. In January 2021 Claris announced that Custom Web Publishing with PHP is being deprecated and they are making changes to how PHP is bundled with FileMaker Server. Please see this support article for further details.

If you are hosting the fmAccountingLinkWebhook.php file on your FileMaker Server the web server “root” folders for FileMaker Server v16 and later are:

Windows:

[drive]:\Program Files\FileMaker\FileMaker Server\HTTPServer\Conf

where [drive] is the drive on which the Web Publishing Engine component of your FileMaker server deployment resides.

Mac OS X (HTTPS):

/Library/FileMaker Server/HTTPServer/htdocs/httpsRoot

N.B. the HTTPS options require a valid SSL certificate to be installed.

Once you have determined the URL to the fmAccountingLinkWebhook.php file you need to create a Webhook within the Xero Developer site for your OAuth 2.0 app. You can follow the Xero instructions for creating a Webhook and enter the URL into the Send notifications to field as well as selecting the event notifications you wish to receive (Contacts and/or Invoices events):

Once you have created and saved the Webhook the status will be ‘Intent to receive’ required and it will generate a Webhook key:

You will need to copy/paste the Webhook key into the fmAccountingLinkWebhook.php file where we set the $myWebhookKey  variable here:

Make sure you also update the $hostname  and $database  variables with the appropriate values for your server/deployment. You can then upload the fmAccountingLinkWebhook.php to your web server and complete the intent to receive validation process. If the ‘Intent to receive’ validation is successful you should see a new record created in the Webhooks table (view the Webhooks layout to see this) and Webhook status will change to OK. You are now ready to start receiving webhooks notifications from Xero.

When the Xero Webhook makes a successful request it performs the following actions:

  • it creates a new record in the Webhooks table and populates the Payload field with the JSON webhook payload data
  • it then performs the processXeroWebHook script which loops through any webhook events in the payload and performs the appropriate actions
  • for CREATE events it will create a new Contact or Invoice record and then call a  subscript to update the Contact or Invoice record from Xero
  • for UPDATE events it will attempt to find the matching Contact or Invoice record using the Xero ID and if a match is found it will then call a  subscript to update the Contact or Invoice record from Xero

We have a video demonstrating the Xero Webhooks setup on the fmAccounting Link (Xero Edition) videos page (or watch on YouTube here). You can get more information about Xero Webhooks on the Xero Developer site here:

https://developer.xero.com/documentation/webhooks/overview

If you would like to implement the Webhooks functionality into an existing v2 integration or v2 of fmAccounting Link you will need to replicate the following from the v2.1 file:

  • create new table occurrences/relationships for InvoicesContactsCheck  and InvoicesContactsCreate  as per the v2.1 file
  • create the following new layouts: Webhooks , WebhooksContacts  and WebhooksInvoices
  • import the following scripts: processXeroWebHook , Webhooks - Update Current Contact from Xero  and Webhooks - Update Current Invoice from Xero
  • grant full access privileges to the script: Xero Authentication - OAuth 2.0 Refresh Access Token
  • create a new Webhooks  FileMaker Account/Privilege Set and add the following extended privileges:

Still need help? Contact Us Contact Us