What are Webhooks?
Webhooks are a way for the TrackRecordPro API to actively notify your application of a change to its data, without your application needing to regularly poll to check for changes, e.g. using a timer. Whenever certain types of data are changed, a webhook is triggered within the TrackRecordPro API. This will cause a web address you have configured within TrackRecordPro to be called automatically for every change with a POST request and data in a pre-determined format.
Configuring Webhooks
To configure which web address is called to notify you, this can be set under the settings section of the TrackRecordPro website:
Once this has been set you will begin to receive notifications. Usually, you will only receive notifications for changes to data within your own company or child companies of that company, however there is a setting (used by the TrackRecordPro developers) which allows for notifications for all data changes within the system across all companies. Access to this setting is restricted and not settable from within the API. To disable webhooks, simply remove your URL from this field.
Important Note
It is recommended that your webhook URL be one that is secured with SSL, e.g. a HTTPS website. If this is the case, the certificate on your website must be valid and externally recognised - there is no option to allow a self signed certificate for webhook usage.
Webhook POST Request Format
When the TrackRecordPro API calls your webhook URL, it will do so by sending a POST request to the web address you specified, which will contain the JSON data as demonstrated in the following example:
{
"notification": {
"id" : 28,
"endpoint" : "assets",
"company_id" : 32,
"api_company_id" : null,
"hook_type" : "UPDATE",
"foreign_key" : 32891,
"date_added" : "2018-07-23 10:09:32",
"failures" : 0,
"http_error_code" : null,
"failure_url" : null,
"last_updated" : "2018-07-23 10:09:32"
},
"change": {
[...]
}
}
Notification object
The first section of the JSON data, "notification", contains the details specifying what has changed and when. The fields within this section will always be:
| Field Name | Content Description |
|---|---|
| id | The ID number of the notification, this will be unique for every notification received. These are incremental, so you can determine if a notification comes before or after another by comparing the ID numbers. |
| endpoint | The endpoint where the data was changed, e.g. "assets", "companies", "users". |
| company_id | The company ID under which the changed data belongs |
| api_company_id | The company ID under which the user who changed the data belongs, if the data was changed by a user on the TrackRecordPro website. You can use this to identify data changed via the website versus data changed via the API. Data changed via the API will always contain NULL in this field, whilst data changed via the website will always contain an integer value. Using this and other factors you can determine which notifications relate to changes you made yourself via API calls and prevent recursive loops of API request and notification. |
| hook_type | This will be one of either "INSERT", "UPDATE", or "DELETE", and indicates if the data provided is being deleted, added, or updated. |
| foreign_key | This is the primary key into the table which is being changed. For example, if the endpoint indicates that the notification is for assets and the foreign_key field contains the value 32, and the hook_type field contains UPDATE, this would indicate that asset ID 32 is being updated. |
| date_added | The date that the request was added to the system. Usually notifications arrive within a couple of seconds of them being actioned, so this is pretty much real-time. |
| failures | The number of previous failed attempts made to contact your webserver with this notification. |
| http_error_code | The last HTTP error code returned by your webserver in the event that the previous attempt failed. |
| failure_url | The last web address that was attempted when trying to deliver this notification, which is useful if you have since changed thee URL in your settings. |
| last_updated | The date that the last attempt to deliver the notification was made, before this one. |
Change object
The second section of the JSON data, "change", contains all the fields of the changed record, as documented in our table list. This is to save you from having to call an API endpoint to retrieve this data. The data will always be that which exists after the change, not before, so in the event of DELETE this can contain an empty object or NULL, as there is no longer any data to provide.
Failures and Retries
In the event that your webhook URL cannot be reached, e.g. due to connection error, access restriction or server error, the notification will be retried. It will be retried every second until the situation is resolved. Note that in this situation, you must ensure that retried notifications are replayed "in order", by comparing the ID of the newly received notification to that of the last received notification, and discarding or logging "out of order" notifications to prevent data loss.
A gauranteed way to ensure that you always have the most recent data when receiving a webhook is to retrieve it via an API endpoint. This way if your data is "out of order" you can ensure that it is updated to the latest data within TrackRecordPro. This will be slower though as you will have to wait for the API call to return data before you can update your own database.
