Configuring webhooks

A webhook is used to notify an external system of an event occurring in Akuiteo. The goal is to exploit data from detected events.

Example

If a system external to Akuiteo is used to manage human resources, a webhook can be set up to notify this external system of the creation or deletion of employees.

In the context of webhooks, an event is composed of two major elements:

The concerned object (ex: an employee, an expense, etc.);
The action performed on this object (ex: creation, modification, deletion).

When a webhook is configured to detect a certain event and that event occurs, the webhook sends a request to a web address called an endpoint.

An endpoint is a hypertext link on an external server that is used to receive requests sent by webhooks.

Each request contains data about the event that occurred, or at least the ID of the object associated with the event.

The webhook detects events in all of Akuiteo. For example, it is not possible to configure a webhook that detects an event performed by a particular user.

The webhooks are configured i the Administration console, from Configuration > Webhooks.

Creating a webhook

In the Webhooks screen, click on New webhook.

Specify the information in the Properties section:

Field	Description
Name	Specify a label to name the webhook.
Endpoint (URL)	Specify the link corresponding to the endpoint of the webhook. The endpoint is the hypertext link on the server that receives the requests sent by the webhook. Click on the Test button at the right of the field to verify the accessibility and validity of the specified endpoint.
Active	You can enable or disable the webhook by clicking on the option. the webhook must be enabled in order to work. If it is disabled, it will not work or send any request. A webhook can be enabled anytime from the Webhooks screen.

Field

Description

Name

Specify a label to name the webhook.

Endpoint (URL)

Specify the link corresponding to the endpoint of the webhook.

The endpoint is the hypertext link on the server that receives the requests sent by the webhook.

Click on the Test button at the right of the field to verify the accessibility and validity of the specified endpoint.

Active

You can enable or disable the webhook by clicking on the option.

the webhook must be enabled in order to work. If it is disabled, it will not work or send any request.

A webhook can be enabled anytime from the Webhooks screen.

Specify the information of the Notification section:

Important

This feature requires enabling the following feature flag: Transverse domain > Notification Echec Webhook label.

Field	Description
Email	Specify the email address to which an email is sent when an error occurs on the webhook.
Enable notification in case of failure	Click on the option to enable or disable the sending of email in case of failure on the webhook.

Specify the information in the Security section:

Field	Description
Secret	Specify the secret if the endpoint uses a secret. Important The endpoint must be an HTTPS website for the secret to work. Note The signature is generated with the HMAC-SHA256 cryptographic protocol in Base64. Behavior When a request is sent by the webhook using a secret, it contains a signature as a header. This signature is a unique combination that depends mathematically on the content of the request and the secret used. The external system receiving the request can be programmed to check this signature. In that case, the system will try to regenerate the signature using the content of the request and the secret: If the regenerated signature is identical to the one in the header of the request, the secret is correct and the content has not been altered. The request's authenticity is then assured. If the regenerated signature is different to the one in the header of the request, the secret might be incorrect or the content of the request might have been altered. The request's authenticity is then not assured.
Header name	Specify the header name if the endpoint uses a security header. The header is a security element that can be used by the endpoint to only accept webhook requests that contain this header and its value specified in the Header value field.
Header value	Specify the value linked to the specified header in the Header name field if the endpoint uses a security header. If the header value specified in the Header value field is different to the one expected by the endpoint, the request might be considered unauthentic and not coming from Akuiteo.

Field

Description

Secret

Specify the secret if the endpoint uses a secret.

Important

The endpoint must be an HTTPS website for the secret to work.

Note

The signature is generated with the HMAC-SHA256 cryptographic protocol in Base64.

Behavior

When a request is sent by the webhook using a secret, it contains a signature as a header. This signature is a unique combination that depends mathematically on the content of the request and the secret used. The external system receiving the request can be programmed to check this signature. In that case, the system will try to regenerate the signature using the content of the request and the secret:

If the regenerated signature is identical to the one in the header of the request, the secret is correct and the content has not been altered. The request's authenticity is then assured.
If the regenerated signature is different to the one in the header of the request, the secret might be incorrect or the content of the request might have been altered. The request's authenticity is then not assured.

Header name

Specify the header name if the endpoint uses a security header.

The header is a security element that can be used by the endpoint to only accept webhook requests that contain this header and its value specified in the Header value field.

Header value

Specify the value linked to the specified header in the Header name field if the endpoint uses a security header.

If the header value specified in the Header value field is different to the one expected by the endpoint, the request might be considered unauthentic and not coming from Akuiteo.

Specify the information in the Event section:

Field	Description
Event type	Select the event type from the drop-down list. The event type corresponds to the type of the object to which the webhook must detect a certain action (ex: an employee, an expense, etc.).
Event action(s)	Select the event action from the drop-down list. It is the action for which the webhook must send a request every time it occurs on the relevant object type (ex: creation, modification, deletion).

Field

Description

Event type

Select the event type from the drop-down list.

The event type corresponds to the type of the object to which the webhook must detect a certain action (ex: an employee, an expense, etc.).

Event action(s)

Select the event action from the drop-down list.

It is the action for which the webhook must send a request every time it occurs on the relevant object type (ex: creation, modification, deletion).

Click on Create.

The webhook is created. It must be enabled in order to work.

Modifying a webhook

On the webhook line, click on

Modify the desired information.

Click on Update.

The webhook is modified.

Configuring the login properties

Under the Akuiteo's login credentials section, specify the user credentials in order to connect to Akuiteo in the context of webhooks.

Field	Description
Akuiteo user	Specify the ID of the user that processes the webhooks and click on Save. It is advised to specify a technical user, that is a user for which Technical user? is checked on the Desktop Application then in People > User management.
Akuiteo password	Specify the password of the user that processes the webhooks and click on Save.
Timeout (endPoint)	It is used to specify the duration (in ms) from which the webhook stops waiting for a response from the server then click on Save.
Maximum number of attempts (1-8)	Specify the maximum number of attempts in case of failure of the request. A request is considered as failed when the HTTP code of the response obtained starts with a number different from 2.
Production retry mode	This option is used to define the behavior of retries in case of failure of requests. The option is checked by default. When the option is checked, the interval between each retry increases exponentially between each retry. The calculation formula of this time is: Timeout (endPoint) + try number⁴ This behavior is recommended if you use webhooks in real conditions because it better manages the simultaneous use of many webhooks. When the option is unchecked, the interval between each retry is 3 seconds. This behavior is recommended only if you want to test webhooks in a test environment because it reduces the interval between retries.

Click on the Test button to test the connection to the Webhook interface using the values specified.

Viewing the webhook requests

The following columns present information about responses to webhook requests.

Field	Description
Latest response	Displays the HTTP response code of the latest request sent by the webhook. If the code obtained starts with 2, the request has succeeded and the cell is green. If the code obtained starts with 4, the request has failed and the cell is red. If the code obtained is N/A, the request has not been send yet.
Successful calls	Displays the number of requests that have successfully reached the endpoint.
Total no. of calls	Displays the number of times the webhook has detected an event and has then sent a request to the endpoint.
Log	The icon in this column allows you to download the log file of the webhook. The log is a .log extension text file that contains the history of all the requests made by the webhook. You can open it with a text editor.