Incoming integration

The Incoming integration allows creating an endpoint that receives data from external systems. This way, there is no need to send data for a particular customer separately. Then, in the Automation module, the received data is processed and, if data contains any customer identifier, it can be transformed into customer’s data.

Incoming integration facilitates a launch of a workflow based on the received data from the external systems. Data sent to the endpoint through Incoming integration must be in the JSON format. If the data is nested, it will be flattened in accordance with the structure.

There are two types of incoming integrations:

• Without authentication - Anyone who have address to the endpoint can send requests.
• With JWT authentication - Each request sent to the endpoint must be authenticated by JSON Web Token (JWT). For this purpose, you must select the API key used for generating a JWT token.
  
  WARNING: You must implement a solution that allows you to authenticate with JWT.

With JWT authentication

1. Go to Automation > Incoming > New integration.
2. On the pop-up, select JWT authentication.

Define endpoint

1. In the Endpoint section, click Define.
2. In the URL field, you can find the endpoint URL which is generated automatically. The endpoint is unique for every integration.
3. From the API key dropdown list, select the key which will be used for generating JWT for authentication. You must implement a solution that allows you to authenticate this way.
   
   Tip: To generate the JWT, use the /uauth/v2/auth/login/profile endpoint .
4. Optionally, you can personalize the integration by adding an icon in Node icon.
5. Confirm the settings by clicking Apply.

Retrieve data

5. In the Incoming data section, click Define.
6. Click Retrieve data.
7. Send a POST request to the endpoint defined in the Endpoint section. The system waits for the incoming request for 1 minute and 30 seconds. On the basis of received data, the system lists parameters which can be used in the future to filter requests.
   If the endpoint receives the data, they appear in flattened form.
8. To see the raw JSON, click the icon.
9. If the received data has the expected structure, confirm by clicking the Apply button.

Requests deduplication

Deduplication is the process that Incoming Integration uses to ensure your workflow only triggers for new information, avoiding duplicates. To prevent duplicated requests, it is possible to select the request parameters from which the deduplication hash will be calculated.

1. To select request parameters, you must first perform instructions described in the “Retrieve data” section in this document.
2. In Deduplication hash generator, click Define.
3. Select up to 5 parameters from which the deduplication hash is to be built. You can use any incoming data from request body and headers.
4. Confirm the settings by clicking Apply.

Before you start using request deduplication, it’s worth reviewing the key concepts:

• all deduplication keys are stored for the 7 days. It means that Synerise deduplicates requests with the same deduplication hash for a period of only 7 days from the last sent request.
• if a duplicated request is sent, Synerise will return 204 HTTP status code
• for non-duplicated request, Synerise will return 200 HTTP status code
• if you would like to provide your own deduplication hash, you can do so by including it in the request headers. In this case, choose only your header in the Deduplication hash generator section in the Incoming Integration settings.

Saving integration

1. To save the integration as a draft, click Save.
2. To save the integration and make it available for use in workflows, click Save & publish.

Without authentication

1. Go to Automation > Incoming > New integration.
2. On the pop-up, select Without authentication.

Define endpoint

1. In the Endpoint section, click Define.
2. In the URL field, you can find the endpoint URL which is generated automatically. The endpoint is unique for every integration.
3. Optionally, you can personalize the integration by adding an icon in Node icon.
4. Confirm the settings by clicking Apply.

Retrieve data

4. In the Incoming data section, click Define.
5. Click Retrieve data.
6. Send a POST request to the endpoint defined in the Endpoint section. The system waits for the incoming request for 1 minute and 30 seconds. On the basis of received data, the system lists parameters which can be used in the future to filter requests.
   If the endpoint receives the data, they appear in flattened form.
7. To see the raw JSON, click the icon.
8. If the received data has the expected structure, confirm by clicking the Apply button.

Requests deduplication

Deduplication is the process that Incoming Integration uses to ensure your workflow only triggers for new information, avoiding duplicates. To prevent duplicated requests, it is possible to select the request parameters from which the deduplication hash will be calculated.

1. To select request parameters, you must first perform instructions described in the “Retrieve data” section in this document.
2. In Deduplication hash generator, click Define.
3. Select up to 5 parameters from which the deduplication hash is to be built. You can use any incoming data from request body and headers.
4. Confirm the settings by clicking Apply.

Before you start using request deduplication, it’s worth reviewing the key concepts:

• all deduplication keys are stored for the 7 days. It means that Synerise deduplicates requests with the same deduplication hash for a period of only 7 days from the last sent request.
• if a duplicated request is sent, Synerise will return 204 HTTP status code
• for non-duplicated request, Synerise will return 200 HTTP status code
• if you would like to provide your own deduplication hash, you can do so by including it in the request headers. In this case, choose only your header in the Deduplication hash generator section in the Incoming Integration settings.

Saving integration

1. To save the integration as a draft, click Save.
2. To save the integration and make it available for use in workflows, click Save & publish.

Example of use

You can check how the incoming integration is used in the Send data from Microsoft Azure Forms to Synerise use case.