Outgoing Integration

The Outgoing Integration module 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 the Analytics module, you can synchronize data by sending them out of Synerise. You can create a reusable and single-use integrations to be used in the workflows.

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.

Creating reusable integration

To create a reusable webhook which can be used in the Outgoing Integration 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. 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.
  • For a detailed guide on managing parameters with schemas, refer to the Managing parameters with schema section.

  

• 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” 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, 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.

1. Go to Automation > Outgoing.
2. In the upper-right corner of the screen, click New integration.
3. In the upper-left corner of the screen, enter a name for the integration.
4. In the Choose connection, click Define.
5. Select one of the authentication methods:

• No authentication - No authentication is required.
• Password - Authentication is based on a log-in and a password to a resource.
  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 need to use:
       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 log-in.
       4. In the Password field, enter the password.
       5. Click Save.
          The connection you created can be used later in other nodes and workflows.

• Token - This method allows you to authenticate by a token.
  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 need to use:
       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 field, enter a token.
       4. Click Save.
          The connection you created can be used later in other nodes and workflows.

• API key - This method is especially useful to the users who use Synerise REST API. When you choose this authorization method, from the dropdown list, you can select an API key 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.
  
  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 need to use:
       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 API key field, paste the API key.
       4. Click Save.
          The connection you created can be used later in other nodes and workflows.

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

   

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.
   
   WARNING: 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)
7. Optional: Upload an icon for the node.
8. 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.
9. Optional, recommended: In the Event name field, choose an action name for the event that contains the request response 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 section.
   • If you leave the field blank, the action defaults to webhook.response.
10. 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, in this part of the process, you will select the schema template you created.

2. In the Parameters 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.

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 section, the request body will be as follows:

   InputOutput

   {
       "field1": "{% context field1 %}",
       "field2": "{% context field2 %}"
   }

   {
       "field1": "Value1",
       "field2": "Value2"
   }

7. 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.
   3. If you want to add more headers, click Add header.

8. Click Apply.

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