Join us at Xero Developer Roadshow, June 2018 at a city near you. Register Free

Xero API Webhooks


What are webhooks?

Webhooks allow you to subscribe to certain events that happen in Xero. It’s limited to contact and invoice events for now. When one of these events are triggered we’ll send a HTTP POST payload to the webhook’s configured URL.

Webhooks are configured on a per-app basis and we will send you events for every Xero organisation connected to the app. Webhooks can only be created for private and partner apps. Public app connections only last for 30 minutes and are not suitable for webhooks.


Events

When you configure a webhook you choose the category of events you’d like to subscribe to. Within each category there are certain types of events that can happen (e.g. create, update).

The available events are:

Event Category Event Type Description
Contact CREATE A new contact has been created
UPDATE An existing contact has been updated (including when contacts are archived)
Invoice CREATE A new invoice has been created
UPDATE An existing invoice has been updated (including when invoices are archived)

Payloads

The JSON payload will be a consistent format for all categories of events. It will consist of:

The Events array The details of the events that you’ve subscribed to
Last Event Sequence The sequence number of the last event in this payload
First Event Sequence The sequence number of the first event in this payload
Entropy A random string to make the payload more cryptographically secure

 

Each Event will consist of:

Resource URL The URL to retrieve the resource that has changed
Resource ID The ID of the resource that has changed (e.g. ContactID)
Event Date UTC The date and time that event occurred (UTC time)
Event Type The type of event of that occurred (e.g. Update)
Event Category The category of event that occurred (e.g. CONTACT). You will only retrieve events from categories that your webhook is subscribed to
Tenant ID The ID of the tenant that the event happened in relation to (e.g. OrganisationID)
Tenant Type The type of tenant, currently this will always be ORGANISATION

Example Payload

{
   "events": [
      {
         "resourceUrl": "https://api.xero.com/api.xro/2.0/Contacts/717f2bfc-c6d4-41fd-b238-3f2f0c0cf777",
         "resourceId": "717f2bfc-c6d4-41fd-b238-3f2f0c0cf777",
         "eventDateUtc": "2017-06-21T01:15:39.902",
         "eventType": "Update",
         "eventCategory": "CONTACT",
         "tenantId": "c2cc9b6e-9458-4c7d-93cc-f02b81b0594f",
         "tenantType": "ORGANISATION"
      }
   ],
   "lastEventSequence": 1,
   "firstEventSequence": 1,
   "entropy": "S0m3r4Nd0mt3xt"

}

The x-xero-signature Header

A hashed signature of the payload is passed along in the headers of each request as x-xero-signature. This signature is used when doing an intent to receive validation.