Webhooks Explained
Introduction
A Webhook is a lightweight package of information sent to a third-party server in order to notify the remote service of a specific event. In the case of QuickFile, Webhooks are well suited to events that do not result directly from an account holder’s input, for example when a client pays an invoice, or accepts/declines a quotation.
Webhooks seek to negate the requirement to repeatedly poll the API for updates and instead will deliver the information to your specified endpoint as and when a specific event occurs.
Enabling Webhooks
Webhooks are available to users with a Power User Subscription. You can access the Webhooks control panel from the main account settings screen under Developer dashboard >> Options >> Webhooks.
To enable the Webhook service you must first provide an endpoint URI that you would like QuickFile to send any notifications to. Once enabled, Webhooks will be delivered to your endpoint within 5-10 minutes of activation for supported events.
Supported Events
Currently, we will fire a Webhook for any of the following supported events. You can click on any of the webhooks to view a more detailed technical spec.
- Invoice/Estimate created
- Invoice/Estimate updated
- Invoice/Estimate deleted
- Invoice/Estimate viewed by client
- Invoice/Estimate paid by client
- Estimate accepted or declined by client
- Client created
- Client updated
- Client deleted
- Client contact created
- Client contact updated
- Client Merged
- Supplier created
- Supplier updated
- Supplier deleted
- Supplier Merged
- PaymentsCreated
Note: Client contacts are individual named contacts associated with a client record, they consist of a full name, email and telephone number.
Webhooks Format
Webhooks are designed to be minimalistic and are delivered over HTTP/HTTPS in JSON format; they do not contain metadata relating to the event but rather the ID values that allow you to pull additional information over the API. Here is an example of a typical Webhook:
{
"PayLoad": {
"InvoicesCreated": [
{
"TimeStamp": "2015-03-26T20:16:52",
"Id": 123456,
"InvoiceType": "INV",
"FromRecurring": false,
"RecurringParentId": 0
}
],
"Timestamp": "2015-03-26T22:03:18",
"Signature": "6b1025b9304caee85895dcdccdcb4500",
"Hookid": "7893782a-bdd3-461c-9c84-f50fe9a6b3da"
}
}
A Webhook will normally be triggered within 10 minutes of the associated event; the process of sending Webhooks is decoupled from the primary QuickFile application and goes into a short queue within a dedicated Webhooks server.
To minimise connection requests, we may batch together several events within a single Webhook payload. Your application should use your chosen language’s native JSON functions or a suitable JSON library to deserialize the JSON and parse out the individual events.
Webhooks Security Considerations
A primary concern regarding Webhook security is ensuring that the Webhook originated from a QuickFile server. Each webhook will contain a couple of extra values that you can use in conjunction with your Secret Key to verify the authenticity.
HookId
A unique GUID assigned to each Webhook sent from QuickFile.
Signature
The signature is simply an MD5 hash of the HookId, Secret Key and QuickFile Account Number. For example:
HookId: 7893782a-bdd3-461c-9c84-f50fe9a6b3da
SecretKey: abc123
AccNumber: 61314000001
Md5Hash(HookId + SecretKey + AccNumber);
Output: 6b1025b9304caee85895dcdccdcb4500
When your application receives the Webhook you can take out the hookId and concatenate it with your locally stored secret key and account number, then compare the resulting MD5 hash. You should have some method of storing all HookIds and only processing each unique HookId once; this will protect you against so-called “Replay Attacks”.
As an additional measure to protect against Man-in-the-Middle attacks (MITM) you should always provide a HTTPS endpoint, otherwise the contents of your webhook will be visible in plain text over the network.
Responding to a Webhook
When a Webhook is sent to your chosen endpoint URI we will listen for a HTTP 200/OK response; this will indicate to us that receipt of the Webhook has been acknowledged by your server.
If any other HTTP response code is issued or the server does not respond within a timely manner then we will assume that the webhook has not been received. In such cases, we will attempt to send the Webhook again 1 hour later. After 3 failed attempts we will give up and, if there are many consecutive failed attempts over a 24-hour period, we will temporarily disable your Webhooks and notify you by email.
Webhooks Diagnostics
To make it easier to audit and diagnose problems with your integration and to provide a test rig, we have built a Webhooks Diagnostics area. Here you will be able to view the raw JSON for any previously issued Webhook in the last 30 days and to resend those Webhooks where applicable.
We will also reveal the HTTP response codes that your server issued along with the timing and response for any retried events.
Webhooks Test Facility
Within the Webhooks diagnostic area we also provide a simple tool to fire a Webhook to your chosen endpoint URI. This service will not send genuine IDs relating to items in your account but it will provide an accurate replication of a live Webhook payload with a single event.
Bear in mind that unlike the test facility, live Webhooks will batch together multiple events into a single payload, so your application should be capable of iterating through each event and processing accordingly.