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

  2. In the Incoming data section, click Define.
  3. Click Retrieve data.
  4. 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.
  5. To see the raw JSON, click the icon.
  6. If the received data has the expected structure, confirm by clicking the Apply button.
Example of retrieved data
Example of retrieved data

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

  2. In the Incoming data section, click Define.
  3. Click Retrieve data.
  4. 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.
  5. To see the raw JSON, click the icon.
  6. If the received data has the expected structure, confirm by clicking the Apply button.
Example of retrieved data
Example of retrieved data

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

Tip: You can check how the incoming integration is used in the use case concerning integration of Microsoft Azure Forms with Synerise.

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.

Example of use
Example of a workflow

  1. Add a Business Event trigger node. In the configuration of the node, select the Incoming integration prepared according to the instructions described in this article. 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",
   "label":"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.
    Example of use
    Example configuration of Outgoing webhook node

    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.

😕

We are sorry to hear that

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

😉

Awesome!

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

Close modal icon Placeholder alt for modal to satisfy link checker