Working with web hooks

For the web hooks types containing NEWNUMBER and OLDNUMBER merge fields, i.e., "Customer updated", "Product updated", "Project updated", "Order updated" and "Invoice updated", the following logic applies:

If OLDNUMBER is blank, NEWNUMBER is the number of a created entity
If NEWNUMBER is blank, OLDNUMBER is the number of a deleted entity
If OLDNUMBER is identical to NEWNUMBER, the properties of the entity have been updated
If OLDNUMBER is different from NEWNUMBER, the entity has been re-numbered, and its properties mayalso have been updated

Note that the defined merge fields are always included, but will be blank if they don't contain any data.

 

Using web hooks

In the example below, the data is included in the query string and the 'Data posted' text area is left empty. Anything you set in the "Data posted" field goes in the body of the POST request.

Example: A "Product updated" web hook on product no. 33 is triggered by an update to the product description.

Web hook definition URL: http://www.domain.tld/webhookservice.aspx?newnumber=[NEWNUMBER]&oldnumber=[OLDNUMBER]

Result: http://www.domain.tld/webhookservice.aspx?newnumber=33&oldnumber=33

You may supply web hook setup instructions to your users as simply a Type and URL pair.

Example: "Navigate to the Web hooks menu by pressing period (.) to enter the QuickSearch popup. Type 'Web hooks' in the search field and click the link in the Extensions section. Click the 'New web hook' button. Create a new 'Product updated' web hook, paste the following into the URL field and then click OK: http://www.domain.tld/webhookservice.aspx?newnumber=[NEWNUMBER]&oldnumber=[OLDNUMBER]"

 

Requests and retries

e-conomic web hooks are not guaranteed to fire instantly, but in most cases they will. Bulk modification of data results in as many triggers of web hook requests to your server as the number of resources you have changed. The web hook requests are not bundled in one call even if they originate from a single API request.

Tip: Instant calls could potentially mean tens if not hundreds of requests to your server within seconds. As such it is recommended that you add these events to a local queue and defer your actions so you don't miss any web hook requests.

If a request to a web hook URL fails, the request will be retried up to 5 times. A failure is either a connection error to the server or a status code that is not in the 2xx range of status codes. The table below shows our retry policy:

After the fifth retry, no more retries are attempted.

If more than 250 requests to a specific web hook URL have failed in the last 24 hours, the web hook will be disabled and no more requests will be fired. We will not queue requests while the web hook is disabled, so all events are lost until you enable the web hook again.

Can I rely on web hooks alone?
As with any asynchronous web communication, there are many moving parts that can fail. So if you rely on web hooks alone, you run the risk of slowly getting out of sync if one or more web hooks fail to be sent, picked up or for some other reason just never makes it to your server.

To ensure consistency across systems, a nightly sync job will make sure that any missed web hooks are caught. Giving your customers a way to manually fire this sync is also a good idea. Before you implement a sync job we recommend that you read more in this blog post.