Introduction

Webhooks can be used to get notified when certain updates are done in Erply. These updates are either generated from database events automatically or by other event triggers in certain processes. The event will trigger a webhook to be sent to configured urls using HTTP Post requests.

Use case example:
Get a notification to a certain HTTP endpoint when a product gets created or updated in Erply.

Please note that this feature is designed to be a fire and forget feature, this means that integrations using this service should not use it as an exact data source rather a notification service.

Note! Do not use this web-hook as a data process trigger (cases where any other data processing logic is done on this same request process before sending a 200 HTTP back to the web-hook request). These web-hooks have a relatively short timeout and any process that does not respond 200 in a timely manner will be cancelled and marked as failed.

Configuration API swagger documentation:
Sandbox
https://webhook-sb.erply.com/api/docs/index.html

Production
https://webhook.erply.com/api/docs/index.html

Setting up

In order to use this feature first we need to set up the configuration for the account. In order to do this we need to use the managers configuration API .

Authentication

The configuration API uses Erply API session keys to authenticate. These configurations are saved for that specific client.

Configuration

The configuration contains the following parameters

• action - This relates to a specific database action (insert, update or delete)

• table - The name for the table that we want to get notified for (ex: product, invoice, user etc). Table names will also define the type of the webhook (read type information in the separate subpages).

• secret - Set a secret for this configuration. Manager will use this as salt for hmac key in the web-hook that can be used to authenticate it.

• endpoint - The URL where the event will be sent.

When the configuration are saved. Then future operations that match the configuration will be used to generate web-hooks.

Webhooks

Every event will not be generated into a web-hook 1 by 1. Instead one web-hook can contain up to 100 database events. The structure of the web-hook that will be sent will be the following

Notice that one of the events has rowId as 0. This means the event did not get a row id. Certain database events do not provide the id’s.
Some table events guaratee id's and some dont.

Timing and Concurrency

Items will contain a timestamp when the action took place, however large operations that will generate a number of web-hooks will not arrive at the same time. For example a large update operation with 5000 updates would generate 50 web-hooks, these 50 web-hooks would not arrive at the same time and some web-hooks might contain items that were actually updated before items on a web-hook that arrived earlier.

Failures

Sender expects 200 HTTP code response for the web-hook request. If one is not provided within 5 seconds then the call is counted as a failed request. Manager can be configured to re-try these failed ones again for configurable amount (currently set to 1). However once this failed limit is reached then this web-hook cannot be re-sent again.

Verifying

When adding the web-hook configuration you can also set a secret for it. This secret is used as salt for the hmac key generation. The hmac uses sha256 as encryption and id of web-hook as the message.

The integration reading the web-hooks can use this to verify the web-hooks if needed.

 

Webhook types

There are different types of webhooks. Although they are configured exaclty the same (only difference being the name of the table parameter) the generated webhook content and available events differ. Check the separate pages for details about the different types.