Nodes:: Webhook node – Emarsys

Important: Please note that the Webhook node is an advanced feature meaning that it requires you to have some technical resources to integrate it with your application(s) and it is your responsibility to make sure that the integrated service operates appropriately.

You can create webhook setups to use in your Automation programs with the Webhook node. This node allows you to establish communication between Emarsys and other customer experience solutions. By using webhooks, you can send data to your external system or application when a contact arrives at the Webhook node within an Interactions or Automation Center journey.

Related pages:

Prerequisites

Only users with Webhook Node Presets Editor Permissions permissions can create, edit or delete Webhook node presets. If you cannot perform such actions, please contact your Account Owner. You can check the user permissions on the Management > User Management page.

You need to have an external system or solution that is ready to receive the event sent by Emarsys (we send the events via POST API requests). Events are sent in JSON format and the structure of contact and additional data consists of a single level. Optionally, you can also send event data attributes that are listed under the event_data object (i.e. in the second level of the hierarchy). For example:

{
"event_time": "2021-04-01T17:08:44Z",
"email_address": "example@emarsys.com" 
"event_data": {
    "event_time": "2021-04-01T17:05:11Z",
    "order_id": 4534322,
    "Order_status": "shipped"
},
"scenario": "shipping_update"
}

Click to copy

Optional prerequisite, if your security measures require you to use an allowlist: The Webhook node will connect to your customer experience solution using specific IP addresses. To allow this node to communicate with your solution, you need to add the following IP addresses to your allowlist:
- 34.89.173.3
- 35.246.249.205
- 34.89.137.140

Use cases

Please take into consideration that the Webhook node was designed for synchronizing contacts with an external solution. We strongly recommend against using this node for other use cases as it may cause performance issues in your programs.

Connecting Emarsys to offline channels

If you would like to connect Emarsys to your offline channels (e.g. 3rd party messaging solutions, distribution centers where you add personalized gifts to the packages and you have direct mail solutions, etc.), then the Webhook node may come in handy.

Creating a Webhook node preset

Here is what you need to do to create a Webhook node preset:

1. Navigate to Automation > Webhook Node Presets and click Create preset.

2. Configure your Webhook node’s Appearance:

a. Enter the name of the preset.

b. Select a node icon. The API node icon is used by default.

You can see how your node looks after selecting the preset in the journey in the Node preview.

3. Configure the Connection.

Please note that you cannot create connections to the api.emarsys.net endpoints with the Webhook node.

a. Specify the API endpoint URL of your external service or application.

Notes:

You need to specify a secure URL, starting with the https:// prefix.
Please do not use URLs pointing to any of the Emarsys endpoints.
If the request fails, the program automatically retries connecting several times and the interval between each retry increases exponentially from 30 seconds to 10 minutes. After the 11th failed attempt, the program will go to Fail-safe mode. Alternatively, if you wish to prevent the program from being put into Fail-safe in the case of minor errors, please ensure error 406 is returned. As a result, contacts will be discarded, but the program will keep on running.

b. Select the Authentication method. The following methods are available:

- HTTP basic authentication - If you select this method, you need to specify your Username and Password.

- JWT authentication - If you select this method, you need to specify your Secret key.

- OAuth2 - If you select this method, you need to specify the Authentication URL, Client ID, Client secret and Scope (optional).

4. Define the event payload. The Webhook node’s payload can contain triggering event data, contact data field values and additional data with static values.

a. Send triggering event data - Select this checkbox if you would like to forward the event payload that triggers the program.

Notes:

Event data attributes are listed under the event_data object.
Please note that event data field mapping is not available.
Event data does not contain metadata, it only includes attributes that are available in the Decision node in Interactions for attribute filtering. This means that the event data containing the same attributes will be sent to the configured endpoint (that triggered the program without any additional data regardless of the nodes the trigger event travelled through).
If you check the Send triggering event data checkbox and use this preset in a program without any event payload (e.g. if the External event that triggered the program contains no payload or in recurring Automation Center programs), then the event_data object will be empty.

b. Contact data - Here you can define key-value pairs to send contact data field values:

- To add a new field, click + Add Field.

- To delete a key-value pair, click the Delete icon.

You can add a maximum of 20 contact fields when defining Contact data key-value pairs.

Notes:

You need to select at least one contact database field to create a valid configuration.
Only Emarsys system and custom fields are available for selection under Contact data.

c. Additional data - These fields can contain static values that are sent with the requests so that your external system can identify their source (i.e. the journey or scenario the event came from) and purpose (e.g. informs a company printing direct mails whether they should print the welcome program or a defecting customer campaign for the specific contact).

To add a new field, click + Add Field. To remove one, click the icon.

You can add multiple additional fields to the payload. These are at the same hierarchical level as contact fields.

Here you can define the following:

Field name - The field/key name that appears in the payload.
Field type - You can choose from the following types: text, numeric or boolean.
Predefined values - Adding values to a field is optional. After entering a value, click Add. You can choose from the following options:
- If you don’t enter a predefined value, then an input field will be available in the node when the preset is selected in a journey where users can enter any value that is of the selected type.
- If you specify only one value, then the payload will always contain that value but users cannot modify it in the Webhook node within the Automation journey (this is useful if you would like to send system IDs to the external system in order to recognize where the request comes from).
- If you add multiple predefined values, then users can choose the value from the dropdown in the Webhook node that will be sent in the payload.

In this case, marketers will see the following options within the Webhook node:

d. Operational data - These are optional event data fields that are added to the Webhook payload request by default. You can deselect and rename these fields.

To ensure the receiving system does not process duplicated messages, we recommend using the deduplication_ID field.

You can choose from the following fields:

- deduplication_id - UUID used to avoid processing duplicate messages.

- ems_program_id - The ID of the program where the Webhook node was triggered.

- event_time - The timestamp indicating when the Webhook node was triggered.

5. To test the connection and authentication and preview the data sent by the program, click Start Testing.

If you would like to test how your program will send the event data, create a program that is triggered by the specific event.

Here you can:

Preview Data - To preview the data, enter the contact’s email address and click Preview Data.

Notes:

You can preview the data and test the connection without saving the preset. This is useful when the preset is already used in active programs and you would like to test the updates before finalizing the changes.
The event_data field contains an empty object because its content heavily depends on the program where the node is used. If you would like to test the request with the event payload, we recommend testing the program.
A random value that matches the selected type is generated for the following fields:
- deduplication_id
- ems_program_id
- additional data

Test Connection - You can test the connection after by triggering your endpoint with the preview data. This option is only available after previewing the data. For more information on the status codes, see Response codes. Here you can see the following:
- Status: The response code received from the endpoint.
- Response: The response body.
- Data preview: The payload sent to the endpoint (that is displayed at the Preview Data step).

Using the Webhook node in an Automation program

1. Open the program where you would like to use the Webhook node and insert it.

2. Double-click the Webhook node and select the required configuration preset from the dropdown. After selecting the configuration preset, the node’s icon and name change accordingly.

3. Here you will see all the data configured in the selected preset:

Notes:

If you would like to add or remove a field, you need to modify the preset. To modify Webhook node presets, the Edit Webhook node presets and Delete Webhook node presets permissions have to be enabled for your user. If you cannot modify presets, please contact your Account Owner.
You cannot modify presets used in Active or Finished programs. In such cases, you need to pause or freeze the programs to modify the preset.

Event data - Here you can see the event data status. The following statuses are available:
- Not sending any data of the triggering event - The program does not send triggering event data.
- Data of the triggering event is being sent - Triggering event data is sent by the program.
Contact data - The list of key-value pairs that are sent with the selected contact data field values.
Additional data - You need to select or enter the static values that will be sent for each processed contact.

This is how a Webhook node looks:

Managing Webhook node presets

Your Webhook node presets are listed on the Automation > Webhook Node Preset page.

Here you can:

Create a Webhook node preset by clicking Create preset.
Copy a preset by clicking the icon.
Edit a preset by clicking the icon.
Delete a preset by clicking the icon.

Response codes

Unsuccessful delivery can put programs into fail-safe mode or exclude contacts from programs. Contacts who exited the program at the Webhook node count as Exited on the Program Reporting page.

Response code	Marked as received	Result
20x (success)	Yes	The application received the data sent by the Webhook node.
30x (redirection)	No	Failed requests are retried, and a program is put into Fail-safe after the 11th failed attempt. Emarsys will not follow the redirection.
406 (not acceptable)	No	The contact will exit the program.
408 (request timeout)	No	Failed requests are retried, and a program is put into Fail-safe after the 11th failed attempt.
429 (rate limited)	No	Failed requests are retried, and a program is put into Fail-safe after the 11th failed attempt.
Other 4xx (client error)	No	Failed requests are retried, and a program is put into Fail-safe after the 11th failed attempt.
5xx (server error)	No	Failed requests are retried, and a program is put into Fail-safe after the 11th failed attempt.

Known issues and limitations

Requests sent by the Webhook node time out after 20 seconds, which means that if the external endpoint doesn't answer within the limit, then the request will fail.
You can add a maximum of 20 contact fields when defining Contact data key-value pairs.
The Webhook node sends requests one by one (not in batches). For example, if you would like to send 1000 events, then one request will contain 1 event or contact at a time.
Before sending events for a large number of contacts, please consider that it might take a while (e.g. if you use the Webhook node in an Automation Center program where you have a contact list with 100,000 contacts, then 1 request will be sent for each contact and contacts can only continue their journey after all responses have been received for every contact from your external system).
Please make sure that your external system is carefully prepared for receiving a large number of events (so the system can handle the load and it will not be considered a DDoS attack).
If you add the Webhook node to Interactions programs, please consider that Emarsys cannot guarantee that the Interactions SLA is consistently met because we need to wait for your external system’s response after sending each event.