So, you are interested in receiving information about data changes in Kerui on your side. For this, humanity came up with the term "webhook". In fact, this is an HTTP POST request that will be sent to your URL when the data you need in Kerui is created/updated/deleted.

For receiving data via webhook or, simply speaking, an HTTP request for a specific data creation/update/deletion event in Kerui, automated scenarios are responsible.

Creating a Scenario

To create a scenario for receiving a webhook, go to Settings / Scenarios and click the Create button.

In the form that appears, specify the name of the scenario, the execution context* (entity), and select the types of events the scenario should react to.

*currently, Kerui allows creating scenarios only for documents. Over time, we will add more contexts.

After creating a new scenario, you will be redirected to the editing page for conditions and execution steps.

Condition

To set the conditions under which the scenario will be triggered, click on the event name.

After that, you can add the scenario trigger conditions you need using the form.

In this example, the scenario will trigger for creating, updating, or deleting documents of type Customer Order where the author is the user Tester Petrovich.

Action

To add an action to send an HTTP request, click the (+) button and select Action.

In the action menu, click on "Send HTTP request".

In the form that appears, you can specify:

• URL address where the HTTP request will be sent

• HTTP method - request method (currently only POST is available)

• Serializer - data serialization type

• HTTP headers - a list of headers that will be part of the sent request

All changes are saved automatically and do not require confirmation.

Scenario Activation

To activate the scenario, click on its status badge next to the name at the top of the editor.

Only active scenarios will execute according to the defined conditions and actions.

Execution

To check the execution, you can try to "trigger" the necessary conditions. For testing, we recommend trying the excellent shareware service https://webhook.site/

In this case, a POST HTTP request with the specified headers was sent to the indicated URL.

We highly recommend using the Authorization header to authorize incoming requests, so as to prevent unauthorized access and data leaks.

Log

You can find the log of all sent requests under Settings / Scenarios / Execution.

Request Execution Errors

If for some reason the specified URL does not respond and the response status is other than a 2xx code, Kerui will retry at a set interval. A maximum of 10 attempts will be made, after which the execution will complete with an error.

Serializer

Standard

By default, Kerui suggests using the standard data serializer, which will use the API queries you are already familiar with, such as getDocument and others, depending on the execution context. You can change the format of the data received in the request by changing the serializer type.

Modified

Allows you to specify only the fields you need.

In this case, when forming the data block, the getDocument request will return a limited number of fields.

Custom

Provides you with full control over the request body, but requires writing a `JSON` serializer using the mustache templating engine.

Metadata

For the standard and modified serializer, Kerui will always wrap the data block in current metadata to make it easier for you to understand the execution context.

{
    "company_id": "d81bfb3b-8e23-4146-ae68-be533d807dbb",
    "context": "documents",
    "data": {...},
    "event": "updated",
    "run_id": "ca23daba-ac09-4009-a732-d7bdb2c75d01",
    "run_number": 78,
    "workflow_id": "fb48ab5c-7154-42f9-902a-f8ce7d01d2e2"
}

{
    "company_id": "d81bfb3b-8e23-4146-ae68-be533d807dbb",
    "context": "documents",
    "data": {...},
    "event": "updated",
    "run_id": "ca23daba-ac09-4009-a732-d7bdb2c75d01",
    "run_number": 78,
    "workflow_id": "fb48ab5c-7154-42f9-902a-f8ce7d01d2e2"
}

{
    "company_id": "d81bfb3b-8e23-4146-ae68-be533d807dbb",
    "context": "documents",
    "data": {...},
    "event": "updated",
    "run_id": "ca23daba-ac09-4009-a732-d7bdb2c75d01",
    "run_number": 78,
    "workflow_id": "fb48ab5c-7154-42f9-902a-f8ce7d01d2e2"
}

• company_id - company identifier

• context - execution entity

• event - event type (created/updated/deleted)

• run_id - execution identifier

• run_number - execution sequence number

• workflow_id - scenario identifier

Variables

For easy reuse of variables and secret keys, we suggest using the variables section.

To add a variable, go to Settings / Scenarios / Variables and click the Add button.

• Key - variable identifier. Only uppercase symbols A-Z and _ can be used

• Value - the direct value of the variable to be used during serialization

• Secret - for highly important and secret values. In this case, these values will be stored in Kerui in an encrypted format, and no one else will be able to read them

• Notes - to avoid forgetting what this variable is for

After saving, all variables will be available in the general table, but secret ones will be almost entirely hidden (except for the first 3 characters).

You can use the variable value using the mustache template engine where inside {{..}} you simply specify the variable key.

During request serialization, the variable key will be replaced by its value. In this way, you can define your variables once and reuse them in all scenarios.

Happy data exchanging!