Outgoing Integration lets you integrate Synerise with any external service. Thanks to the possibility of building HTTP requests and supplementing them with customer attributes or data calculated by Decision Hub, you can synchronize data by sending them out of Synerise. You can create a [reusable](#creating-reusable-integration) and [single-use](#creating-single-use-integration) integrations to be used in the [workflows](/docs/automation/creating-automation). ## Creating single-use integration If you only need to configure a webhook to integrate with an external source for a specific workflow, we recommend creating an integration that only exists in that workflow by [using the **Outgoing Integration node**](/docs/automation/actions/webhook-node). ## Creating reusable integration To create a reusable webhook which can be used in the [Outgoing Integration node](/docs/automation/actions/webhook-node), perform the instructions described in this section. ### Deciding the approach - **Use schema builder to create a schema template** - Schema builder lets you create a form which you can use further in the [Outgoing Integration node](/docs/automation/actions/webhook-node). This way, you will configure the node by filling out the form with values which you want to send to the external source eliminating the need to repeatedly define the HTTP method, endpoint, authorization, and request body. Additionally, you can populate fields with variables sourced from the profile/event context, as well as utilize Jinjava for retrieving aggregate or expression results. - To create the form, follow the instructions available in the [Schema builder documentation](/docs/assets/schema-builder/creating-schemas). - For a detailed guide on managing parameters with schemas, refer to the [Managing parameters with schema](/developers/inserts/automation#managing-parameters-with-schemas) section.
Diagram
Schema template in the Outgoing Integration node
- **Send a custom request body** - You can skip creating a schema template and go straight to creating the outgoing integration that sends a request to a defined endpoint with the same request body which you will define in the ["Enter request body"](#enter-the-request-body) section in this document. The request can contain variables sourced from the profile/event context as well as Jinjava inserts to retrieve analyses results. If you use such integration in the [Outgoing Integration node](/docs/automation/actions/webhook-node), the node won't require further configuration. ### Creating the integration #### Define the connection --- In this part of the process, you define the authentication method and providing the information required to establish a connection.
Outgoing Integration creation page
Outgoing Integration creation page
1. Go to Automation Hub icon **Automation Hub > Outgoing**. 2. In the upper-right corner of the screen, click **New integration**. 1. In the upper-left corner of the screen, enter a name for the integration. 3. In the **Choose connection**, click **Define**. 4. Once the section is expanded, select the authentication method: - **No authentication** - No authentication is required. - **Login & Password** - This method lets you use basic authentication to authenticate with the remote server.
Click here to see the instructions
  1. Click Select connection.
  2. In the connection list:
    • If the connection you want to use is in the list, select it and proceed to Defining endpoint.
    • If the connection list is empty or you don't see a connection, you must:
      1. At the bottom of the dropdown list, click Add connection.
      2. In the Connection name field, enter the name of your connection (it's visible only on the Select connection dropdown list).
      3. In the Login field, enter a login.
      4. In the Password field, enter the password.
      5. Click Create.
        The connection you created is saved and can be used later in other nodes and workflows.
- **Custom connection** - This method sends an authentication token request before executing the main request defined in the Outgoing integration node settings. The token is fetched when the request data is uncached, then cached according to its TTL, and added to the target request.
Click here to see the instructions
  1. Click Select connection.
  2. In the connection list:
    • If the connection you want to use is in the list, select it and proceed to Defining the request section in this article.
    • If the connection list is empty or you don't see a connection, you must:

      1. At the bottom of the dropdown list, click Add connection.

      2. In the Authorization request tab, click Define.
        Result:

        The Request section in the configuration of a custom connection
        The Request section in the configuration of a custom connection

      3. In the Connection name field, enter the name of your connection (it's visible only on the Select connection dropdown list or on the list of connections in Settings > Connections).

      4. In Secret, enter a value which is required in the request to obtain a token. This value will be anonymized and displayed as asterisks.

      5. In the Headers section, add request headers (in the left field, enter the key; in the right, enter its value).

      6. In the Body field, enter the request body.
        For example: 

        { "api-key": "{{secret}}" }

        where {{secret}} retrieves the value of the Secret field to anonymize the token.

      7. Confirm the settings in the Authorization request tab by clicking Apply.

      8. In the Token placement settings section, click Define.

      9. Click Retrieve response.
        Result:

        Retrieved token in the Response section in the custom connection configuration form
        Retrieved token in the Response section in the custom connection configuration form

      10. If you:

      • specify the value in the Headers section, the extracted authorization data from the response will be added as a header to the target request.

      • provide the value in the URL Parameters section, the data will be appended to the target request’s URL as a parameter.
        You can use the following values to retrieve values from the response:

        • authResponseBody - a variable that contains the full body of an authentication response

        • authResponseStatusCode - a variable that contains the status code of an authentication response

        • authResponseHeaders- a variable that contains the headers of an authentication response
          For example: 

          Bearer {{ authResponseBody | fromjson | attr("token") }}

        It takes the JSON response body stored in authResponseBody, parses it into a usable structure, and extracts the value of the token field. Outputs a string like: Bearer "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

      1. In TTL field, specify the how long the cached response from the external request will be valid.
        If you leave this field empty, it's 60 seconds.
      2. Confirm by clicking Apply.
- **Synerise API key** - This method is particularly recommended for the users who use Synerise REST API. It lets you select a connection that includes an [API key](/docs/settings/tool/api) with the required permissions. This way, the requests to Synerise API are executed by this integration and a JWT is not required as it is generated while sending requests and attached to the request headers.
Click here to see the instructions
  1. Click Select connection.
  2. If the connection you want to use is in the list, select it and proceed to Defining endpoint.
    • If the connection list is empty or you don't see a connection, you must:
      1. At the bottom of the dropdown list, click Add connection.
      2. In the Connection name field, enter the name of your connection (it's visible only on the Select connection dropdown list).
      3. From API Key dropdown, select API key you want to use. If you don't see any API Keys on the list, verify if you are assigned with a user role that includes permissions to preview API keys.
      4. Click Create.
        The connection you created can be used later in other nodes and workflows.
- **OAuth2 Client Credentials** - This method lets you use your OAuth2 credentials to authorize.
Click here to see the instructions
  1. Click Select connection.
  2. In the connection list:
    • If the connection you want to use is in the list, select it and proceed to Defining endpoint.
    • If the connection list is empty or you don't see a connection, you must:
      1. At the bottom of the dropdown list, click Add connection.
      2. In the Connection name field, enter the name of your connection (it's visible only on the Select connection dropdown list).
      3. In the Token endpoint URL field, enter the URL used to obtain an access token from the authorization server.
      4. In the Client ID field, enter a unique identifier assigned to your application by the service provider.
      5. In the Client secret field, enter a confidential key issued alongside the Client ID. It is used to securely authenticate your application.
      6. Optionally, in the Scope field, define the level of access your application is requesting. Scopes specify which actions or data your application can access (for example, read user data, send messages). Refer to the API documentation for the correct scope values.
      7. Click Create.
        The connection you created is saved and can be used later in other nodes and workflows.
- **API Key** - This method lets you authenticate using an API secret by including it in a header of your choice or in a URL parameter — example outputs: - the authorization header: `Authorization: Bearer [secret]` - URL parameter: `client_id=[rendered secret]`. When you use this connection in the Outgoing Integration node, the token will be automatically added to either the request header or the request URL with every request.
Click here to see the instructions
  1. Click Select connection.
  2. If the connection you want to use is in the list, select it and proceed to Defining the request section in this article.
    • If the connection list is empty or you don't see a connection, you must:
      1. At the bottom of the dropdown list, click Add connection.
      2. In the Connection name field, enter the name of your connection (it's visible only on the Select connection dropdown list).
      3. In the Secret field, enter an API Key.
      4. If you:
        • specify the value in the Headers section, the API key will be added as a header to the request. For example, x-api-key: {{secret}} where {{secret}} retrieves the value of the Secret field to anonymize the API key value.
        • provide the value in the URL Parameters section, the API key will be appended to the request’s URL as a parameter.
      5. Click Create.
        The connection you created can be used later in other nodes and workflows.
- **SHA256-based authentication** - *This method is recommended exclusively for connecting with Eagle Eye*. This method lets you authenticate using SHA256 algorithm. When a target request is sent, the following headers are added to the request: - **X-EES-AUTH-CLIENT-ID** – the value is taken from the Client ID field. - **X-EES-AUTH-HASH** – the value is generated by concatenating the endpoint URI, request body, and client secret, then hashing the result using SHA256.
Click here to see the instructions
  1. Click Select connection.
  2. In the connection list:
    • If the connection you want to use is in the list, select it and proceed to Defining the endpoint section in this article.
    • If the connection list is empty or you don't see a connection, you must:
      1. In the Connection name field, enter the name of the connection.
        It's used to find the connection on the list.
      2. In Client ID, enter a unique identifier assigned to your application by the service provider.
      3. In Client secret, enter client secret assigned to your application by the service provider.
      4. Confirm by clicking Create.
#### Define the endpoint --- In this part of the process, select the HTTP method and define the endpoint to which you will send a request from Synerise. Additionally, you can define the name of the event which will contain the request response when the **Outgoing Integration** node is triggered. 4. In the **Destination endpoint** section, click **Define**.
The Defining endpoint section in the process of creating an outgoing integration
The Defining endpoint section in the process of creating an outgoing integration
All fields that contain Snippet icon accept [snippets](/docs/assets/snippets) or [inserts](/developers/inserts). If you use this integration in a [business workflow](/docs/glossary#business-workflow), profile-related inserts cannot be used.
5. From the **URL** drop-down list, select an HTTP method. 6. In the **URI address** field, enter the endpoint. The URI can contain inserts.
This field doesn't allow the endpoints defined as IPs (for example, `51.145.180.18`). You can only use endpoints that contain a domain (for example, `https://example.com`)
4. **Optional:** Upload an icon for the node. 5. In the **Webhook name** field, enter the value that will be displayed in the `name` parameter of the event which will contain the request response. 2. **Optional, recommended:** In the **Event name** field, choose an action name for the [event that contains the request response](/docs/assets/events/event-reference/integration#webhookresponse-and-custom-webhook-response-names) from your selected endpoint. We recommend using a meaningful name instead of the default one. - from the dropdown list, you can select the name of the event (event action) that will be generated when a request from this node will be executed. - at the bottom of the dropdown list, you can create a new event using the **Create new event** option. **Result**: A pop-up appears. Fill out the configuration form on the pop-up, according to instructions in step 3 in the [Adding event definitions - in the Web application](/docs/assets/events/event-definitions#in-the-web-application) section. - If you leave the field blank, the action defaults to `webhook.response`. 7. Click **Apply**. #### Select the schema template --- This part of the process is optional. If you took the **Use schema builder to create a schema template** approach described in [Creating reusable integration](#creating-reusable-integration), in this part of the process, you will select the schema template you created.
Selecting a schema in the process of creating an outgoing integration
Selecting a schema in the process of creating an outgoing integration
2. In the **Configuration schema** section, click **Define**. 3. From the **Schema template** drop-down list, select a schema you created before. 4. Click **Apply**. #### Enter the request body --- In this part of the process, enter a body that contains all parameters and their values which you will send in a request.
Sending out an example request to the endpoint defined in the outgoing integration process
Sending out an example request to the endpoint defined in the outgoing integration process
5. In the **Webhook payload** section, click **Define**. 6. In the **Payload** text box, enter the JSON payload schema. This JSON schema can include inserts. By filling out fields with dynamic data using Jinjava as described in the [Managing parameters with schemas](/developers/inserts/automation#managing-parameters-with-schemas) section, the request body will be as follows: 
{
       "field1": "{% context field1 %}",
       "field2": "{% context field2 %}"
   }
{
       "field1": "Value1",
       "field2": "Value2"
   }
14. In the **Headers** sub section, add headers in the following way: 1. In the **Key** field, enter the header name. 2. In the **Value** field, enter the header value. The key and value can contain inserts. 1. If you want to add more headers, click **Add header**. 15. Click **Apply**. ### Custom response event parameters You can add up to 10 custom parameters in each event that is generated from the response to the request that was sent. This solution allows for even more precise identification of response events, the creation of more detailed analyses and reports, and more accurate error handling.
The Additional parameters section
The Additional parameters section
1. To define the custom event parameters, in the **Additional parameters** section, click **Define**. 2. Click **Add parameter**. 3. In the **Parameter** field, enter the name of the parameter. - The name must not contain special characters or exceed 128 characters - The following parameters cannot be sent: - `eventUUID` - `status` - `statusDescription` - `uuid` - `clientId` - `diagramId` - `diagramName` - `blockId` - `blockName` - `req` - `name` - `body` 4. In the **Value** field, enter the parameter value. - The value is always sent as a string when the event's JSON payload is generated. The maximum length of the value is 230 characters. - You can use dynamic values in the **Value** field. 5. If you want to add more parameters, click **Add parameter**, and repeat steps 3-4. ### Saving the integration In the upper-right corner: - to save the outgoing integration as a draft, click **Save**. - to save and make the outgoing integration available for use in workflows, click **Save & publish**.