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.
↪ 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.
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) |
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 |
{
"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"
}
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.