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 e-conomic, 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 an HTTP POST request to the URL defined in the webhook setup.

Webhooks can, amongst other things, be used to trigger object synchronization between e-conomic and external systems, thus saving the external solution from having to constantly poll for changes in e-conomic data.

Webhook types

The Webhooks API offers a dedicated endpoint that lists all the supported webhook types. The response also includes a human-readable description for each event

How to set up webhooks

Webhook subscriptions can be managed using the Webhooks API. It offers offers full CRUD operations for webhooks, allowing you to programmatically create, retrieve, update, and delete subscriptions.

Important note!

Consuming webhooks requires you to be able to handle queueing of incoming events as these may come in large numbers in rapid succession. Any business logic that needs be performed based on webhooks should be run separately without locking the HTTP processes to ensure that you can still respond to webhooks.

We offer a guide on setting up a webhook consumer service here.

Requests and retries

e-conomic wehooks 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 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 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.

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.