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 holders 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.

Webhooks are available to users with a Power User Subscription. You can access the Webhooks control panel from the main account settings screen under “3rd Party Integrations”.

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.

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 contact deleted *
• Client Merged new
• Supplier created new
• Supplier updated new
• Supplier deleted new
• Supplier Merged new
• PaymentsCreated new

* Client contacts are individual named contacts associated with a client record, they consist of a full name, email and telephone number.

Webhooks are designed to be minimalistic and are delivered over HTTP/HTTPS in JSON format, they do not contain meta data 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:

A Webhook will normally be fired 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.

A primary concern regarding Webhook security is ensuring that the Webhook originate 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:

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 preferably only provide a HTTPs endpoint, otherwise the contents of your webhook will be visible in plain text over the network.

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.

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.

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.