Webhooks enable you to create custom integrations and let Bloomreach Engagement communicate with different services via APIs (HTTP request). Webhooks provide a way to send automated messages via scenarios to a third party or, the other way around, retrieve data from a third party. Using standard scenario flow you can for example set up a webhook to be always triggered after a certain event occurred. Webhooks can be used for various use cases such as triggering an action in a third-party platform, sending leads to call centers, or retrieving third-party data to enrich your campaigns or single customer view, and many others.

We also provide several predefined webhook templates for interacting with multiple platforms like Facebook, Whatsapp, Zapier, Slack, and others.

Where to find webhook templates

1. Go to Campaign > Scenario
2. Create new
3. Actions > Other

Alternatively, set up a webhook integration in Integrations -> Add new integration -> Webhook preset.

If your desired platform is not on the list you can still create an empty webhook to connect to any API via an HTTP request.

Setting up a Webhook

Webhook setup consists of two main parts: Endpoint and Payload.

Under Endpoint select the appropriate HTTP method (GET, POST, PUT, PATCH or DELETE) and enter the endpoint URL.

Under Payload using the code editor enter the desired API payload. On the right side of the editor, you can select the type of payload format: JSON, TEXT, or XML. You can also use jinja to create dynamic personalized payload or template parameters to create easily editable fields. Created parameters will be accessible under the Parameters tab.

Webhook batching

When you are setting up an integration with a 3rd party, they usually have an API that can handle multiple operations in one request. Usually, each webhook creates an individual request. However, batching changes this and merges multiple webhooks into a single request. The benefit of implementing batching is to have faster processing which is necessary for high volume campaigns.

How to batch webhooks

To batch multiple customers into one request access webhooks and click on ‘Batch webhook’. This allows you to set up a custom template for the batch request as well as the template for individual customers. The resulting batch request may contain up to 1000 customers.

If you click on the Batch webhook it transforms the Editor Tab, showing to templates:

• Root serves as the master template.
• Customer provides you with Jinja customer context, the output is in the form of a string.

Sending SMS in batches

You can use batch webhooks to send bulk SMS messages to multiple recipients at once through the Messaging API of our default SMS provider, the CM Telecom Business. To do so refer to their API documentation.

API accepts payload in the following format:

{
    "messages": {
        "authentication": {
            "producttoken": "00000000-0000-0000-0000-000000000000"
        },
        "msg": [ 
            {
                "allowedChannels":  ["RCS", "SMS"],
                "from": "SenderName",
                "to": [{
                    "number": "00447911123458"
                },{
                    "number": "00447911123459"
                }],
                "body": {
                    "type": "auto",
                    "content": "Other Test message"
                }
            }
        ]
    }
}

We need to split this request into Root and Customer template, which would look like this:

{
    "messages": {
        "authentication": {
            "producttoken": "00000000-0000-0000-0000-000000000000"
        },
        "msg": [ 
            {
                "allowedChannels":  ["RCS", "SMS"],
                "from": "SenderName",
                "to": [
                  {% output customers separated by ',\n ' %}
                ],
                "body": {
                    "type": "auto",
                    "content": "Other Test message"
                }
            }
        ]
    }
}

{ "number": "{{ customer.phone }}" }

Other useful commands

[
  {% output customers separated by ',\n  ' %}
]

{{ customers | join(",") }}

{{ customers | length }}

{% for item in customers %}
    {{ (item | from_json).name }}
    {% if not loop.last %},{% endif %}
{% endfor %}

Other Tabs

The Parameters tab is where all the bracket parameters are pulled.

The Settings tab allows you to set the Batch size where you can change the number of customers which will be rendered into a single batch request. The number can be anything from 1 to 1000. However, while the algorithm is optimized for the best performance of the Bloomreach Engagement platform, this number is not always reached and guaranteed.

🚧

Too much personalization may lead to timeouts. We, therefore, recommend lowering the number of batch size.

The Test webhook button allows you to render the request with non-personalized data.
The Done button sends the rendered request

Batching on-events campaigns

Batching on-events campaigns is a special case that happens only when multiple events are fed into Bloomreach Engagement at the same time. The approach is:
There is a system scenario that is triggered by an event and that sends batched calls to other third parties
other scenarios generate the events that trigger the system one, thus at some point, the system scenario gets a steady feed of new events that are successfully batched
The size of the batch may vary, it could be 180 or 170, etc. with a maximum limit of 200.

Using webhook responses

When working with webhooks in scenarios, you can process the webhook response as JSON or TEXT. For the JSON format, use the following Jinja command {{ webhook.json_response_property_name }} for a single webhook or the last webhook in your scenario. In case you have multiple webhooks you can also use {{ webhook(x).json_response_property_name }}, where x indicates the order number of the webhook in the particular scenario path. For the TEXT format access the response text via Jinja command {{ webhook.data }} or {{ webhook(x).data }}.
Webhook responses can also be accessed via Jinja using the webhook action id that generated it: {{ webhook.by_action_id(x).data }}.

Webhook can process the responses up to 64KB of raw unparsed data.

Preparing your API endpoint

Do you want to connect Bloomreach Engagement to your RESTful system? Our webhooks expect the API on the other side to work within some standards. Have a look at this article to prepare your API endpoint.

Webhook authentication

When you send campaigns through 3rd party platforms using webhooks, you can select which authentication should be used.

You can find available authentication methods in Data and Assets > Integrations > +Add new integration by selecting the tag Authentication.

HTTP Authentication Schemas

Use HTTP Authentication Schemas when API requires credentials in HTTP headers. You can read more on HTTP authentication on MDN web docs:HTTP authentication.

Endpoint
Enter the endpoint prefix that will be enforced for webhooks using this authentication. For security reasons, Bloomreach Engagement will enforce sending credentials only to defined endpoints and paths under it. For example, if the endpoint prefix is https://secure.example.com/api/v1 then webhook may use endpoint https://secure.example.com/api/v1/send_sms but not https://secure.example.com/api/v2/send_sms, because the later one does not have a compatible path.

Basic Authentication

The Basic HTTP Authentication Scheme for Webhooks connecting to 3rd party APIs. HTTP Basic Authentication is defined in RFC 7617.

You are required to enter Username and Password. These are securely stored in Bloomreach Engagement and will not be displayed to anyone after saving.

Custom headers

Define custom headers for other types of HTTP Authentication Schemas, for example, the Bearer token authentication (RFC 6750), Proxy-Authorization header (RFC 7235).

You are required to enter headers in Key-Value pairs. Pairs marked as _secret_ are securely stored in Bloomreach Engagement and won't be displayed to anyone after saving. _Public_ headers will be visible to users with access to Integrations.

Test settings

Optionally, you can test entered credentials by providing a method and path for HTTP requests. Test endpoint must accept empty request body, validate the credentials, and must respond with HTTP 200 Success for the test to succeed.

Users can select which authentication method to use in Webhooks and Webhook presets.
This enables separate responsibilities: the developer sets up the authentication integration and creates a Webhook preset, then marketing users can use the preset without entering the credentials.

Responsys authentication

This feature is currently available in the Alpha version.

If you are using Oracle Responsys Marketing Cloud Service, you use Responsys authentication to connect to Responsys REST API. Webhooks using this authentication will be authorized to access Responsys's REST API and upon successful authentication, a token and an endpoint are returned to be used by Bloomreach Engagement.

Bloomreach Engagement uses the REST API v1.3 endpoints which are intended for use with Oracle Responsys 20 A and later. Read more on Responsys's authentication on official Oracle docs and Oracle Responsys Developer Guide.

To set up the integration, you need to fill out the following fields:

• Login endpoint (e.g. https://ws.responsys.net/, Obtain the Oracle Responsys REST API endpoint that corresponds to the Oracle Responsys pod for your account)
• Username (The username of a user created in Responsys's account management)
• Password (We recommend using only strong passwords)

🚧

Bloomreach Engagement requires that credentials entered here are exclusive for this integration and must not be used elsewhere.

The user must have a minimal set of roles and a strong password. The Responsys Account Administrator should create a new user on the Account > User management > Manage Users page in the Oracle Responsys Marketing Cloud web portal.

Throughput policy

Throughput policy represents a setting and a scope that throughput of webhooks is limited to. When multiple webhooks share a single Throughput policy, the throughput of all webhooks will be throttled up to the maximum number of concurrent connections defined in the policy. This policy is created on the project level similar to Frequency policy.

📘

Throughput policy should be used when the 3rd party API imposes some limitations on requests per minute or number of concurrent requests.

Setting up a Throughput policy

1. Create a Throughput policy in the Project settings > Campaigns > General > Throughput policies. There you can set individual parameters of the specific policy such as the Concurrency limit which limits the number of concurrent requests.

🚧

Remember that the concurrency limit is just an approximation of the requests per second, as the actual limit always depends on the latency of the API on the other side. It is always better to use sub-optimal requests per second to ensure you won't go over the limit, and it is also good practice to be aware of what happens if the limit is reached.

2. In the Settings of the individual webhook, you can choose to use an established Throughput policy or create a new one by clicking on the Cog button and setting it there.

📘

When deleting a Throughput Policy, a window will pop up, informing you of all active campaigns in which it is being used. In order to delete it, you will either have to find a new Throughput policy for these active campaigns or to stop them altogether.

🚧

On-event campaigns are generally processed with higher priority compared to the rest of the campaigns. However, setting a Throughput policy for webhooks in on-event campaigns may negatively affect the priority in which these webhooks are processed.

Changing throughput policy in running scenarios

When changing from policy A to policy B in a webhook that is actively running, policy B will be applied only to newly executed webhooks, while already scheduled and running webhooks will use policy A. If you want the changes to be applied immediately, the scenario must be restarted. However, when you chang a concurrency limit in policy within a running scenario, the change is applied immediately.

🚧

Migration

If the webhook was previously using the old Speed limits, they can be still used there. However, it is not possible to create a new webhook with old Speed limits. All new webhooks must use a new Throughput policy to limit their speed.

Webhook preset

A Webhook preset is a reusable webhook template that can be be used in Scenarios. To create a Webhook preset go to Data & Assets > Integrations > Add new integration > Webhook preset. The process of setting it up is the same as for a regular webhook explained above.

📘

Imports/Exports

Bear in mind that since version 1.180, it is possible to export/import webhooks across different instances, however, the encrypted parts of the webhook, such as secret headers, or username and password in the case of legacy webhooks, is not exported. The integration ID in webhooks using authentication integrations is also not exported. After importing in a new instance, these parts have to be added manually.

Webhook fail branch

A webhook fail branch allows you to specify further action for customers who did not manage to go through the webhook node. This can sometimes happen due to number of different reasons such as skipping due to consent & policy, aborting due to used Jinja or other technical failures. In the Evaluation tab, you will be able to observe them under the Failed category. To set it up, simply connect desired nodes to the fail branch as seen below: