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.
• 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 this way.

Configuration

With JWT authentication

1. Go to Automation > Incoming > New integration.

2. On the pop-up, select JWT authentication.
   In the Endpoint section, the endpoint URL is generated automatically. The endpoint is unique for every integration.

3. From the API key dropdown list, select the key which has permissions to authenticate. This API key is used to generate the JWT token used for authentication. You must implement a solution that allows you to authenticate this way.
   

   Tip: You can find more information about generating JWT token here.

4. Optionally, you can personalize the integration by adding an icon.

5. Confirm the settings by clicking Apply.

6. In the Incoming data section:

7. Click Retrieve data.

8. 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.
   

9. To see the raw JSON, click the icon.

10. If the received data has the expected structure, confirm by clicking the Apply button.

11. Publish the integration by clicking Save & publish.

    

Without authentication

1. Go to Automation > Incoming > New integration.

2. On the pop-up, select Without authentication.

3. In the Endpoint section, the endpoint URL is generated automatically. The endpoint is unique for every integration.

4. Optionally, you can personalize the integration by adding an icon.

5. Confirm the settings by clicking Apply.

6. In the Incoming data section:

7. Click Retrieve data.

8. 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.
   

9. To see the raw JSON, click the icon.

10. If the received data has the expected structure, confirm by clicking the Apply button.

11. Publish the integration by clicking Save & publish.

    

Example of use

Prepare a simple integration which is triggered by an incoming request received by the Business Event node. The data received in the request is used in a structure that is required to send a profile event.

1. Add a Business Event trigger node. In the configuration of the node, select the Incoming integration prepared according to the instructions described in the Configuration section. Configure the incoming integration so it receives data about products in the cart and the email as the identifier.
   

   Click to see example data received from external service

   {
       "body": {
       "customer_email": "example@example.com",
       "order_number": "111111111",
       "type": "email",
       "language": "eng",
       "products": [
          {
           "name": "Earwax",
           "category": "Hygiene",
           "id": "abcdefgh",
           "image_url": "http://exampleimage.url",
           "product_url": "http://exampleproduct.url",
           "group_id": "groupid"
       } 
   ]
   }
       
   "businessProfileId": 611,
   "endpointId": "XXXX-XXXX-XXXX-XXXX-XXXXXXXXXX",
   "eventId": "XXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
   "headers": {
   "X-Request-ID": "XXXXXXXXXXXXXXXXXXX",
   "X-Forwarded-Host": "example host",
       },
   "method": "POST",
   "time": 1583206296408
   }

2. Connect the Business Event trigger node with the Outgoing Integration node. In the configuration of node:

   1. In the Action name, enter the name of the event.
   2. Select the POST method.
   3. Enter the endpoint URL: https://{SYNERISE_API_BASE_PATH}/v4/events/custom
   4. In the request body, enter the JSON of a custom event.
      
      Click to see example request body

         {
         "action":"goal.achieve",
         "client":{
            "email":"{{request.body.customer_email}}"
         },
         "params":{
            "created_at":"2021-04-28T14:09:27.000Z",
            "group_id":"{{request.body.group_id}}",
            "image_url":"{{request.body.customer_email}}",
            "name":"{{request.body.name}}",
            "product_url":"{{request.body.product_url}}"
         }
      }

   5. Select the appropriate authorization method.

   

   To pass further the values received in the Incoming integration to the Outgoing integration node, use Jinja.

   • For the parameters in the request body, use {{request.body.paramName}}
   • For the parameters in the request headers, use {{request.headers.headerName}}

   Example

   • To pass the value of customer_email, in the body of the Outgoing Integration enter:
     {{request.body.customer_email}}
   • To pass the value of the X-Request-ID header, in the body of the Outgoing Integration enter:
     {{request.headers["X-Request-ID"]}}

3. Connect the Outgoing Integration with the End node.
   Result: A custom event is generated on a customer’s profile.