
## 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](/docs/automation/triggers/businees-event-trigger) to trigger [workflows](/docs/glossary#workflow) 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](#creating-incoming-integration) section explains the steps in the process and logic.


<div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content">

In the workflow, you can refer to the [parameters of request headers and body from the incoming request](/developers/inserts/automation#request-context).

</div></div></div>


## Requirements
---
- You must have the following user permissions to be able to create incoming integrations:
  - [access Automation Hub](/docs/settings/identity-access-management/permissions/automation-permissions#access-the-automation-hub)
  - [see incoming/outgoing integrations](/docs/settings/identity-access-management/permissions/automation-permissions#see-incomingoutgoing-integrations)
  - [create and edit incoming/outgoing integrations](/docs/settings/identity-access-management/permissions/automation-permissions#create-and-edit-incomingoutgoing-integrations)
  - [publish incoming/outgoing integrations](/docs/settings/identity-access-management/permissions/automation-permissions#publish-incomingoutgoing-integrations)
- If you plan to use JWT for request authorization, create a [workspace API key](/docs/settings/tool/api#adding-api-keys) 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](#creating-incoming-integration).

## Authorization
---

The following authorization methods are supported:

| Method             | Description                               | Header                          |
|--------------------|-------------------------------------------|--------------------------------|
| None               | You can disable the authorization requirement.                | N/A                            |
| JWT Authentication | Requires a JSON Web Token (JWT). To generate the token, use the [Log in as Workspace method](https://developers.synerise.com/DataManagement/DataManagement.html#tag/Authorization/operation/profileLogin). | `Authorization: Bearer {jwt_token}` |
| Meta authentication | SHA-256 signature required only for the [Webhooks from Meta](/docs/automation/integration/webhook-from-meta).  | `X-Hub-Signature-256: sha256={signature}` |

## Other headers
---

| Header                | Type   | Description                                                            | Required                     |
|-----------------------|--------|------------------------------------------------------------------------|------------------------------|
| Content-Type          | string | Must be `application/json`                                            | Yes                          |
| X-Deduplication-Hash | string | Custom hash to identify duplicate requests and avoid multiple triggers | Optional                     |

## 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


<pre><code class="language-json">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"
}'</code></pre>


#### With authorization


<pre><code class="language-json">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"
}'</code></pre>


## Response


<div class="content-tabs" data-tab-group="tabgrp-1288">
<div class="tab-buttons"><button class="tab-button" data-tab-id="tabgrp-1288-0" data-tab-group="tabgrp-1288" data-tab-active="true">200</button><button class="tab-button" data-tab-id="tabgrp-1288-1" data-tab-group="tabgrp-1288">400</button><button class="tab-button" data-tab-id="tabgrp-1288-2" data-tab-group="tabgrp-1288">401</button><button class="tab-button" data-tab-id="tabgrp-1288-3" data-tab-group="tabgrp-1288">403</button><button class="tab-button" data-tab-id="tabgrp-1288-4" data-tab-group="tabgrp-1288">404</button></div>

<div class="tab-panel" data-tab-id="tabgrp-1288-0" data-tab-group="tabgrp-1288" data-tab-active="true">

`OK`

</div>

<div class="tab-panel" data-tab-id="tabgrp-1288-1" data-tab-group="tabgrp-1288">

This error means that something is wrong with your JSON structure. Check for missing brackets, commas, unescaped quotation marks, and so on.

<pre><code class="language-JSON">{
    "error": "Bad Request",
    "message": "Error while deserializing input",
    "status": 400,
    "timestamp": "2025-09-17T10:25:32.050812543Z"
}</code></pre>

</div>

<div class="tab-panel" data-tab-id="tabgrp-1288-2" data-tab-group="tabgrp-1288">

This error means that something is wrong with the authorization. Make sure that your token is still valid.

<pre><code class="language-json">{
    "status": 401,
    "error": "Missing 'Authorization' header or 'access_token' cookie",
    "message": "",
    "timestamp": "2025-09-17 11:13:18Z"
}</code></pre>

</div>

<div class="tab-panel" data-tab-id="tabgrp-1288-3" data-tab-group="tabgrp-1288">

This error occurs when the API key selected in the configuration of the incoming integration lacks permissions. For the list of required permissions, see ["Requirements"](#requirements).

<pre><code class="language-json">{
    "status": 403,
    "error": "Forbidden",
    "message": "",
    "timestamp": "2025-10-03 10:44:52Z"
}</code></pre>

</div>

<div class="tab-panel" data-tab-id="tabgrp-1288-4" data-tab-group="tabgrp-1288">

This error occurs when you make a request to a non-published endpoint or the endpoint URL is incorrect. Make sure you copied the entire URL.
```
The requested resource could not be found but may be available again in the future.
```

</div>
</div>


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

| Step | Description                                                                                                     |
|-------|-----------------------------------------------------------------------------------------------------------------|
| **Select authentication method**     | Select authentication method to secure the integration. You can choose from the following options: **JWT authentication**, **Without authentication**, **Webhook from Meta**                     |
| **Send sample data**     | Enable data retrieval and send a request to the endpoint within 90 seconds to retrieve and view all parameters in Synerise. Use this information to test if the result meets your expectations. |
| **Set deduplication rules**     | (Optional) Set deduplication rules to prevent duplicate data if needed.                         |
| **Publish the incoming integration**     | Publish the integration to make the endpoint publicly accessible and allow sending data. |


1. Go to **Automation Hub > Incoming > New integration**.
2. On the pop-up, select:

    
   <div class="content-tabs" data-tab-group="tabgrp-1289">
   <div class="tab-buttons"><button class="tab-button" data-tab-id="tabgrp-1289-0" data-tab-group="tabgrp-1289" data-tab-active="true">With JWT authentication</button><button class="tab-button" data-tab-id="tabgrp-1289-1" data-tab-group="tabgrp-1289">Without authentication</button><button class="tab-button" data-tab-id="tabgrp-1289-2" data-tab-group="tabgrp-1289">Webhook from Meta</button></div>

   <div class="tab-panel" data-tab-id="tabgrp-1289-0" data-tab-group="tabgrp-1289" data-tab-active="true">

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

      <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content">

      To generate the JWT, use the [`/uauth/v2/auth/login/profile` endpoint](https://developers.synerise.com/DataManagement/DataManagement.html#operation/profileLogin).

      </div></div></div>

   3. Optionally, you can personalize the integration by adding an icon in **Node icon**.  
       <figure><img src="/api/docs/image/54176ad07f146575310749eba44b7c2f42c1b327/docs/automation/_gfx/endpoint-jwt-auth.png" class="full" alt="The Endpoint section while creating an incoming integration in Automation Hub"><figcaption>The Endpoint section while creating an incoming integration in Automation Hub</figcaption></figure>  

   3. Confirm the settings by clicking **Apply**.
   4.   
      1. In the **Incoming data** section, click **Define**.  
      2. Click **Retrieve data**.  
          <figure><img src="/api/docs/image/54176ad07f146575310749eba44b7c2f42c1b327/docs/automation/_gfx/retrieve-data.png" class="full" alt="The Retrieve data option in the Incoming data section while creating an incoming integration in Automation Hub"><figcaption>The Retrieve data option in the Incoming data section while creating an incoming integration in Automation Hub</figcaption></figure>
      2. 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.  
      3. To see the raw JSON, click the <img src="/api/docs/image/54176ad07f146575310749eba44b7c2f42c1b327/icons/see-raw-json-icon.png" alt="Code icon" class="icon" >icon.
      4. If the received data has the expected structure, confirm by clicking the **Apply** button.
   <figure>
   <img src="/api/docs/image/54176ad07f146575310749eba44b7c2f42c1b327/docs/automation/_gfx/incoming-webhook-data.png" alt="Example of retrieved data" class="full">
   <figcaption>Example of retrieved data</figcaption>
   </figure>

   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**.  
       <figure><img src="/api/docs/image/54176ad07f146575310749eba44b7c2f42c1b327/docs/automation/_gfx/deduplicate-data.png" class="full" alt="The Deduplication hash generator section while creating an incoming integration in Automation Hub"><figcaption>The Deduplication hash generator section while creating an incoming integration in Automation Hub</figcaption></figure>
   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.
   2. 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.

   </div>

   <div class="tab-panel" data-tab-id="tabgrp-1289-1" data-tab-group="tabgrp-1289">

   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**.  
       <figure><img src="/api/docs/image/54176ad07f146575310749eba44b7c2f42c1b327/docs/automation/_gfx/without-jwt-auth.png" class="full" alt="The Endpoint section while creating an incoming integration in Automation Hub"><figcaption>The Endpoint section while creating an incoming integration in Automation Hub</figcaption></figure>   

   3. Confirm the settings by clicking **Apply**.
   3.   
      1. In the **Incoming data** section, click **Define**.  
      2. Click **Retrieve data**.  
          <figure><img src="/api/docs/image/54176ad07f146575310749eba44b7c2f42c1b327/docs/automation/_gfx/retrieve-data.png" class="full" alt="The Retrieve data option in the Incoming data section while creating an incoming integration in Automation Hub"><figcaption>The Retrieve data option in the Incoming data section while creating an incoming integration in Automation Hub</figcaption></figure>
      2. 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.  
      3. To see the raw JSON, click the <img src="/api/docs/image/54176ad07f146575310749eba44b7c2f42c1b327/icons/see-raw-json-icon.png" alt="Code icon" class="icon" >icon.
      4. If the received data has the expected structure, confirm by clicking the **Apply** button.
   <figure>
   <img src="/api/docs/image/54176ad07f146575310749eba44b7c2f42c1b327/docs/automation/_gfx/incoming-webhook-data.png" alt="Example of retrieved data" class="full">
   <figcaption>Example of retrieved data</figcaption>
   </figure>

     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**.  
         <figure><img src="/api/docs/image/54176ad07f146575310749eba44b7c2f42c1b327/docs/automation/_gfx/deduplicate-data.png" class="full" alt="The Deduplication hash generator section while creating an incoming integration in Automation Hub"><figcaption>The Deduplication hash generator section while creating an incoming integration in Automation Hub</figcaption></figure>
     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.
     2. 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.

   </div>

   <div class="tab-panel" data-tab-id="tabgrp-1289-2" data-tab-group="tabgrp-1289">

   The full instructions are available in [Webhooks from Meta](/docs/automation/integration/webhook-from-meta).

   </div>
   </div>




### 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-cases/send-data-from-forms) use case.

