Webhook authentication

When you send campaigns to third-party platforms using webhooks, you can choose from four authentication methods: HTTP authentication, OAuth 2.0, Responsys authentication (Alpha), and mTLS. Pick the one that matches what your third-party platform requires.

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

HTTP authentication schemas

Use HTTP authentication schemas when the API you're connecting to requires credentials in HTTP headers. Read more on HTTP authentication on MDN web docs.

Endpoint

Enter the endpoint prefix that will be enforced for webhooks using this authentication. For security reasons, Bloomreach only sends credentials to the endpoint and paths you define. For example, if the endpoint prefix is https://secure.example.com/api/v1, the webhook may use the endpoint https://secure.example.com/api/v1/send_sms but not https://secure.example.com/api/v2/send_sms, the latter doesn't have a compatible path.

Basic authentication

The Basic HTTP authentication scheme for webhooks connecting to third-party APIs. HTTP Basic Authentication is defined in RFC 7617.

You are required to enter the Username and Password. These are securely stored in Bloomreach and won't be displayed to anyone after saving.

Custom headers

Define custom headers for other types of HTTP authentication schemas, for example, Bearer token authentication (RFC 6750), proxy-authorization header (RFC 7235).

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

Test settings

You can also test your entered credentials by providing a method and path for HTTP requests. The test endpoint must accept an empty request body, validate the credentials, and 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.

Some infrastructure auto-suspends or scales to zero when idle, such as a self-hosted database or a serverless function. If your endpoint runs on this type of infrastructure, health checks can prevent it from suspending. This adds to your costs even when no import is running. Review your infrastructure's auto-suspend behavior to manage costs between imports.

OAuth 2.0 authentication

Use OAuth 2.0 authentication when the platform you want to connect to via a webhook uses OAuth API authentication. This lets you connect to third-party platforms, such as:

• Microsoft Azure
• commercetools
• Criteo Marketing
• Salesforce Marketing Cloud
• Listrak

Supported flows of OAuth 2.0 authentication

This authentication supports platforms that use the OAuth 2.0 flow grant_type=client_credentials (known as the two-legged OAuth flow). Other flows, like grant_type=authorization_code (known as the three-legged OAuth flow), aren't supported.

To find which flow a platform uses, go to that platform's API documentation and look for the Authentication chapter. There, you can see which authentication method is used (for example, OAuth) and which flow it uses (for example, grant_type=client_credentials).

OAuth 2.0 authentication configuration

To create a successful OAuth 2.0 authentication configuration, provide the following:

• Token endpoint: A URL responsible for generating an access token, which is used in your webhooks. To find it, go to the API documentation of the third party you want to connect with and search for the Authentication chapter. The token endpoint usually has this structure: https://api.example.com/oauth2/token. The token request must include "token_type": "Bearer" as a required parameter.
• Client ID, Client Secret: This pair of credentials is unique and shouldn't be shared publicly with anyone, as it allows access to your private data. Generate these credentials following the process described in the third party's API documentation, then enter them in the client_id and client_secret fields.

Token endpoint validation

For security reasons, Bloomreach validates that the token endpoint and the webhook's endpoint use the exact same base URL.

For example, say you want to send data to a third party via webhook using the endpoint https://api.example.com/list/customers. Since this platform uses OAuth 2.0 authentication, you create the OAuth 2.0 authentication inside Bloomreach.

• If the token endpoint shares the same base URL as the webhook — for example, https://api.example.com—validation passes.
• If the token endpoint uses a different base URL than the webhook—for example, https://auth.example.com —validation fails.

To let OAuth 2.0 authentication send data via webhooks using different base URLs, enable the toggle below the Token endpoint field called Allow webhooks from domains other than the token's endpoint, then list all base URLs used for webhooks. In the example above, that would be https://api.example.com.

Every platform can have a different API specification, so Bloomreach lets you send the client authentication (a token created using client_id and client_secret) in webhooks as Auth Header, Body, or Query Parameter, to cover all possible cases.

Some platforms also require extra parameters—such as scope, which defines what permissions a token grants. You can add these as additional fields in the Body or as a Query Parameter of the token endpoint.

For security reasons, if you update the token endpoint or allowed domains on a saved OAuth 2.0 authentication, you must re-enter your client_id and client_secret.

Once your OAuth 2.0 authentication is successfully saved, you can use it for webhooks to send data to platforms such as Microsoft Azure, commercetools, Criteo Marketing, Salesforce Marketing Cloud, Listrak, and many more.

Responsys authentication

This feature is available in the Alpha version.

If you use Oracle Responsys Marketing Cloud Service, use Responsys authentication to connect to the Responsys REST API. Webhooks using this authentication are authorized to access the Responsys REST API, and on successful authentication, a token and an endpoint are returned for Bloomreach to use.

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

To set up the integration, fill out the following fields:

• Login endpoint: For example, 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.

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.

mTLS authentication

Mutual Transport Layer Security (mTLS) authentication (or client certificate authentication) is a security protocol that enhances authentication in a networked environment. It's based on Transport Layer Security (TLS), a protocol for secure online communication.

mTLS authentication offers robust security by verifying the identities of both clients and servers during communication. Its two-way authentication and encryption capabilities make it a powerful tool for safeguarding sensitive data, preventing unauthorized access, and ensuring the integrity of networked interactions—valued by financial and banking institutions.

When linking Bloomreach to external platforms via webhooks, you can choose mTLS for added security.

Set up mTLS authentication

Step 1: Create a new mTLS Integration

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

Step 2: Provide the Client Certificate and Private Key to be used by Bloomreach

You may use one of the following methods to upload the client certificate:

• Upload a .pem file.

• Provide a URL that hosts the .pem file.
• Paste the contents of the certificate.

Certificate requirements

• Only the .pem file format is supported.
• Password-protected files aren't supported.
• Self-signed certificates (signed by a custom/non-public CA) aren't supported. Uploading this kind of certificate results in a connection error.
• If you edit an existing mTLS integration, you won't be able to view the previously uploaded certificate and key file, for security reasons. You'll need to provide both the certificate and the private key again when making any changes.
• The server certificate must be signed by a trusted Certificate Authority (CA). Bloomreach uses the Mozilla CA bundle.

Step 3 (Optional): Test against a mock Endpoint

This step helps confirm that the certificate and private key were successfully accepted by the server endpoint. To test, fill in the details in the Test settings section and click Test integration in the top right corner.

Step 4: Set up the Webhook to use the above-created mTLS authentication

Within the Webhooks Settings tab, you should see available mTLS integrations under the ‘Authentication’ section.

Only mTLS integrations for which the certificate hasn't yet expired will be visible in the list for selection.