What are webhooks?

Ref. developer.xero.com/documentation/webhooks/overview

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 be created on all apps, although you would need to use the offline_access scope in order to maintain the connection longer than 30 minutes.

↪ Note: There should be at least one organisation connected to the app in order to receive the events payload. This Postman tutorial can guide you through connecting an organisation.

---

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 CategoryEvent TypeDescription

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.