Working with webhooks

What is a webhook?

A webhook is an event notification that you can set up such that when certain events happen in Reviso, an external system will be automatically notified. Technically, this means that when a resource, e.g. an invoice or a product, is changed we invoke a http GET or POST request to any URL defined in a webhook listening on the event.

Webhooks are typically used to trigger synchronization between Reviso and external systems where data may be edited in either system, thus saving you from having to frequently check whether changes have been done in Reviso.

To set up webhooks in Reviso, go to All settings -> Extensions -> Webhooks. If you want to learn more about webhooks, visit webhooks.org.

Webhook types

Below you can see the different webhooks available in Reviso.

Each webhook supports a number of merge fields that you can choose to include in the http request invoked by the webhook. This way, you can set up e.g. an "Invoice booked" webhook URL to automatically include the invoice number.

For the webhooks 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 may also have been updated

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

Using webhooks

You can choose to have the data sent to you using either a GET or a POST. In the example below, the data is included in a query string and the 'Data posted' text area is left empty. You can also omit the query string from the URL and create a JSON template with the placeholders in the 'Data posted' text area.

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

Webhook 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 webhook setup instructions to your users as simply a Type and URL pair.

Example: "Navigate to the Webhooks 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 webhook' button. Create a new 'Product updated' webhook, paste the following into the URL field and then click OK: http://www.domain.tld/webhookservice.aspx?newnumber=[NEWNUMBER]&oldnumber=[OLDNUMBER]"

Requests and retries

Reviso webhooks are not guaranteed to fire instantly, but in most cases they will. Bulk modification of data results in as many triggers of webhook requests to your server as the number of resources you have changed. The webhook 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 webhook requests.

If a request to a webhook 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 or 3xx range of status codes. The table below shows our retry policy:

Retry no.	Time since last failure
1	1 second
2	20 seconds
3	1 minute
4	5 minutes
5	20 minutes
-	Logged as failed

 

After the fifth retry, no more retries are attempted.

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

New Webhook Service ( Beta )

Our new webhook service,currenlty in beta,will behave just as another API endpoint. You can use it to create/edit new webhooks against business events that we support.  Webhooks once created and registered with a URL will receive a payload of data any time the business event is fired. 

To know more on how to use and what business events we support read more at our API Documentation

Can I rely on webhooks alone?

As with any asynchronous web communication, there are many moving parts that can fail. So if you rely on webhooks alone, you run the risk of slowly getting out of sync if one or more webhooks 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 webhooks are caught. Giving your customers a way to manually fire this sync is also a good idea.