Page Contents

Table of Contents

Before you start
How do I enable Webhooks?
Which events send a Webhook?
What does a Webhook look like?
How do I check that a Webhook came from QuickFile?
How should my server respond to a Webhook?
Where can I see the Webhooks that were sent?
How do I send a test Webhook?
Troubleshooting
Related topics

Hide

Webhooks Explained

A Webhook is a lightweight package of information sent to a third-party server to notify the remote service of a specific event. In 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 or declines a quotation.

Webhooks mean you no longer need to poll the API repeatedly for updates. QuickFile delivers the information to your specified endpoint as and when a specific event occurs.

Before you start

A Power User Subscription.
An endpoint URI on your own server that can receive the Webhooks. Use an HTTPS endpoint (see Webhooks Security Considerations).

How do I enable Webhooks?

You can open the Webhooks control panel from Account Settings, or from the Developer Console.

Click Account Settings in the top menu.
Click the Integrations tab.
Click Webhooks. The Developer Console - Webhooks page opens.

Alternatively, open the Developer Console, click Options and choose Webhooks.

The Webhooks page has three options: Enable Webhooks, View previous webhooks and diagnostics, and Webhooks Documentation.

Click Enable 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.

Which events send a Webhook?

Currently, QuickFile fires a Webhook for any of the following supported events:

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

Please note: Client contacts are individual named contacts associated with a client record. They consist of a full name, email and telephone number.

What does a Webhook look like?

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, QuickFile 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.

How do I check that a Webhook came from QuickFile?

A primary concern regarding Webhook security is ensuring that the Webhook originated from a QuickFile server. Each Webhook contains a couple of extra values that you can use, together with your Secret Key, to verify its authenticity.

Value	What it is
HookId	A unique GUID assigned to each Webhook sent from QuickFile.
Signature	An MD5 hash of the HookId, your Secret Key and your QuickFile Account Number.

For example, with these values:

Value	Example
HookId	7893782a-bdd3-461c-9c84-f50fe9a6b3da
SecretKey	abc123
AccNumber	61314000001

Md5Hash(HookId + SecretKey + AccNumber);

Output: 6b1025b9304caee85895dcdccdcb4500

When your application receives the Webhook, take the HookId, concatenate it with your locally stored Secret Key and account number, and compare the resulting MD5 hash with the Signature. Store every HookId and process each unique HookId only once; this protects you against so-called “Replay Attacks”.

Important: Always provide an HTTPS endpoint. This protects against Man-in-the-Middle attacks (MITM); with an HTTP endpoint the contents of your Webhook are visible in plain text over the network.

How should my server respond to a Webhook?

When QuickFile sends a Webhook to your endpoint URI, it listens for an HTTP 200/OK response. This tells QuickFile that your server has received the Webhook.

If your server returns any other HTTP response code, or does not respond in a timely manner, QuickFile assumes that the Webhook has not been received and sends it again 1 hour later. After 3 failed attempts QuickFile gives up. If there are many consecutive failed attempts over a 24-hour period, your Webhooks are temporarily disabled and you are notified by email.

Where can I see the Webhooks that were sent?

The Webhooks Diagnostics area makes it easier to audit and diagnose problems with your integration. Webhooks are archived here for 1 month. You can view the raw JSON for any previously issued Webhook and resend those Webhooks where applicable. It also shows the HTTP response codes that your server issued, along with the timing and response for any retried events.

Open the Webhooks page (see How do I enable Webhooks?).
Click View previous webhooks and diagnostics. The Webhooks - Diagnostics page opens.

Item	What it shows
Queued Webhooks	The number of Webhooks currently waiting to be sent.
Date	The day whose Webhooks are listed. It starts on today’s date.
`Refresh`	Reloads the list for the selected date.
`Send Test Webhook`	Sends a test Webhook (see the next section).

When there are no Webhooks for the selected period, the list shows “No Webhooks found for the selected period”.

How do I send a test Webhook?

The Webhooks Diagnostics page also has a simple tool to fire a Webhook to your chosen endpoint URI. This service does not send genuine IDs relating to items in your account, but it provides an accurate replication of a live Webhook payload with a single event.

Open the Webhooks - Diagnostics page.
Click Send Test Webhook.

Please note: Unlike the test facility, live Webhooks batch together multiple events into a single payload, so your application should be able to iterate through each event and process it accordingly.

Troubleshooting

My endpoint is not receiving Webhooks

Check that your endpoint URI is correct and that your server returns an HTTP 200/OK response. Open the Webhooks - Diagnostics page to see the Webhooks that were sent, the HTTP response codes your server issued, and the timing and response for any retried events.

I received an email saying my Webhooks were disabled

QuickFile temporarily disables your Webhooks when there are many consecutive failed attempts over a 24-hour period. Make sure your server returns an HTTP 200/OK response, then check the Webhooks - Diagnostics page.

One Webhook contains several events

QuickFile may batch together several events in a single payload to minimise connection requests. Use your language’s JSON functions to loop through each event in the payload.

The Webhook has an ID but no invoice or client details

Webhooks contain only ID values, not metadata about the event. Use the ID to pull the full record over the API.