Webhook integration issue

Webhooks are finicky things to integrate with and require careful testing. In your documentation, you say:

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.

This is a problem. It means the live webhook service is returning a structurally different response from the test service. That is a nightmare for integration, because you cannot properly check that your integration works before letting it loose in production.

As a minimum, it would be helpful to have a sample of a live webhook to work from. And it’s pretty important to know whether the structure of the live webhook will always be the same. What happens when a webhook sends only one event? Does it still use the same structure as a webhook sending a batch of events, or does it fall back to the simpler structure used by the test webhooks?

On a similar topic, I’ll also mention in general it would be very helpful to have a “test mode” for Quickfile accounts. This is common practice among many services, such as Stripe. These services give you “live” API credentials and “test” API credentials. The test API works exactly the same as the live one, except that it doesn’t make any real transactions, and there might also be a “test_mode” flag or similar.

The lack of a test mode means I’ve ended up with a separate dummy Quickfile account for testing things. Well actually I have three – one real, one for a staging site, and one for running automated tests.

Hi @MikeHopley

The structure remains the same, you may just see more than one event being included.

For example, this is a single webhook:

{
    "PayLoad": {
        "InvoicesViewed": [
            {
                "TimeStamp": "2022-01-31T23:55:00",
                "Id": 12345678,
                "InvoiceType": "INV",
                "ClientId": 12345678,
                "ClientContactId": 12345678
            }
        ],
        "Timestamp": "2022-02-02T00:00:00",
        "Signature": "******************************",
        "Hookid": "******-****-****-****-******"
    }
}

But on the occasion that you have multiple events, there’s just be multiple events under PayLoad. For example:

{
    "PayLoad": {
        "InvoicesUpdated": [
            {
                "TimeStamp": "2022-01-31T23:55:00",
                "Id": 12345678,
                "InvoiceType": "INV"
            }
        ],
        "InvoicesSent": [
            {
                "TimeStamp": "2022-01-31T23:55:00",
                "Id": 12345678,
                "InvoiceType": "INV"
            }
        ],
        "Timestamp": "2022-02-02T00:00:00",
        "Signature": "******************************",
        "Hookid": "******-****-****-****-******"
    }
}

Or for two of the same type of events:

{
  "PayLoad": {
    "InvoicesUpdated": [
      {
        "TimeStamp": "2022-02-01T23:55:00",
        "Id": 12345678,
        "InvoiceType": "INV"
      },
      {
        "TimeStamp": "2022-02-01T23:55:00",
        "Id": 12345678,
        "InvoiceType": "INV"
      }
    ],
        "Timestamp": "2022-02-02T00:00:00",
        "Signature": "******************************",
        "Hookid": "******-****-****-****-******"
  }
}

Hope this helps!

1 Like

Thanks very much for the quick response, Mathew, that’s just the documentation I needed!

That all looks straightforward and puts my mind at rest.

1 Like