Incoming integration

Overview

An incoming integration is a custom endpoint you create in the Synerise platform to receive data from external systems. You can create this endpoint on the interface in the Synerise platform in Automation > Incoming.
You can use this with the "Business Event" node to trigger workflows by sending a request from somewhere in your infrastructure to the custom endpoint exposed by Synerise.

This article outlines the feature information and the Creating incoming integration section explains the steps in the process and logic.

Requirements

• You must have the following user permissions to be able to create incoming integrations:
  • access the Automation module
  • see incoming/outgoing integrations
  • create and edit incoming/outgoing integrations
  • publish incoming/outgoing integrations
• If you plan to use JWT for request authorization, create a workspace API key with the following permission: INCOMING_WEBHOOK_EXECUTE

Endpoint

The URL to which the request can be sent is unique and generated automatically in the Synerise interface when you create an incoming integration.

Authorization

The following authorization methods are supported:

Other headers

Request body

The endpoint accepts a JSON payload containing any key-value structure. Nested JSON objects are automatically flattened, enabling their parameters to be used directly in the filter to define the conditions which will trigger a workflow.

• Flattening converts nested keys into dot notation or other flat structures.
• Up to 5 parameters from the body and/or headers can be selected in Synerise UI for deduplication hash creation.

Example request

Without authorization

curl --location 'https://api.synerise.com/automation-endpoint/endpoints/authorized/XXXXXX-XXXX-XXXX-XXXX-XXXXXXXX/trigger' \
--header 'Content-Type: application/json' \
--data-raw '{
  "complaint": {
    "id": "cmp-20240610-001",
    "customer": {
      "id": "c123456789",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "jane.smith@example.com",
      "phone": "+1234567890"
    },
    "dateReceived": "2024-06-10T09:15:30Z",
    "orderId": "o987654321",
    "issueType": "product_defect",
    "description": "The wireless headphones stopped working after two days of use.",
    "priority": "high",
    "status": "new",
    "attachments": [
      {
        "fileName": "photo_of_defect.jpg",
        "fileUrl": "https://example.com/uploads/photo_of_defect.jpg"
      }
    ]
  },
  "source": "customer_support_portal"
}'

With authorization

curl --location 'https://api.synerise.com/automation-endpoint/endpoints/authorized/XXXXXX-XXXX-XXXX-XXXX-XXXXXXXX/trigger' \ 
--header 'Content-Type: application/json' \ 
--header 'Authorization: Bearer {JWT}' \ 
--data-raw '{ 
  "complaint": {
    "id": "cmp-20240610-001",
    "customer": {
      "id": "c123456789",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "jane.smith@example.com",
      "phone": "+1234567890"
    },
    "dateReceived": "2024-06-10T09:15:30Z",
    "orderId": "o987654321",
    "issueType": "product_defect",
    "description": "The wireless headphones stopped working after two days of use.",
    "priority": "high",
    "status": "new",
    "attachments": [
      {
        "fileName": "photo_of_defect.jpg",
        "fileUrl": "https://example.com/uploads/photo_of_defect.jpg"
      }
    ]
  },
  "source": "customer_support_portal"
}'

Response

{
    "error": "Bad Request",
    "message": "Error while deserializing input",
    "status": 400,
    "timestamp": "2025-09-17T10:25:32.050812543Z"
}

{
    "status": 401,
    "error": "Missing 'Authorization' header or 'access_token' cookie",
    "message": "",
    "timestamp": "2025-09-17 11:13:18Z"
}

{
    "status": 403,
    "error": "Forbidden",
    "message": "",
    "timestamp": "2025-10-03 10:44:52Z"
}

The requested resource could not be found but may be available again in the future.

Creating incoming integration

The table below outlines the steps which you will go through in this part of the process. The step-by-step instructions on creating the integration are under the table.

1. Go to Automation > Incoming > New integration.

2. On the pop-up, select:

   With JWT authenticationWithout authenticationWebhook from Meta

   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.

   7. In the Incoming data section, click Define.
   8. Click Retrieve data.

      

   9. Send a POST request to the endpoint defined in the Endpoint section. The system waits for the incoming request for 90 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.
   10. To see the raw JSON, click the icon.
   11. If the received data has the expected structure, confirm by clicking the Apply button.

   

   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 section, 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.

   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.

   6. In the Incoming data section, click Define.
   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 90 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.

   

   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 section, 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.

   The full instructions are available in Webhooks from Meta.

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.