Creating API endpoint for webhooks

This guide explains how to build an API endpoint that works with Bloomreach's "Per customer" webhook. Use it if you want to connect Bloomreach to your own RESTful system.

Overview

This article covers:

• What response codes from your API mean to Bloomreach.
• What performance your API needs to meet.
• What security elements you can use to protect your data in transit.

API requirements

Your API must meet the following requirements:

• Provide an HTTPS endpoint with an SSL certificate signed by one of the trusted CAs. Review the trusted CA list.
• Handle concurrent requests. You can configure the concurrency limit per webhook.
• Respond in less than 1,000 ms.
• Return HTTP 200 for success or processing failure.
• Return HTTP 400 for errors or invalid requests to notify Bloomreach to stop sending more requests.
• Return HTTP 500 to notify Bloomreach to retry the same request later.
• Accept and respond with JSON.
• Authenticate requests with an HTTP authorization header (HTTP Basic Auth described in RFC 2617).

Response codes

HTTP 200

Return HTTP 200 whenever a request was received, parsed, and passed initial validation.

{
    "success": true,
    "result": {
        "code": 1,
        "status": "sent",
        "message: "SMS message sent successfully"
}
}

If request processing fails due to input specific to a single request, return HTTP 200 with an error message.

{
    "success": false,
    "errors": [
        { "code": 1004, "description": "SMS message too long. Limit is 160 characters."
    ]
}

HTTP 4xx

Each HTTP 4xx response is recorded as a campaign event with the status "failed."

The following error codes are exceptions that stop the webhook from sending any further requests for all chunks: 400, 404, 410, 412, 413, and 418.

A chunk is a group of customers that entered the scenario at the same time, for example via a Now trigger or a regularly triggered scenario. For event-triggered scenarios, every customer is a separate chunk.

Do not return HTTP 4xx if the request is invalid only for one customer due to webhook personalization. For that case, use the "Per customer" webhook, which sends and processes one customer at a time. Note that this approach increases the load on your API endpoint.

For batch webhooks, it's not possible to identify from the response which batched customer caused the error. A 4xx response is therefore tracked as a failure event for all customers in the batch, even those who did not cause the error.

Typical examples:

• 400 Bad request: the request generated by Bloomreach is invalid due to an incorrect webhook definition.
• 401 Unauthorized: credentials are not provided or are invalid.
• 404 Not found.

HTTP 500

HTTP 500 indicates that your API is unavailable to process the request. Bloomreach retries the request later.

Retry policy

Bloomreach retries requests on the following conditions:

• HTTP 500 Internal Server Error or higher.
• HTTP 429 Too Many Requests.
• Infrequent connection issues: timeout, reject, or drop.

The maximum number of retries is 3, for a total of 4 request attempts. Batch webhooks with a batch limit of 10 or above may retry up to 7 times, for a total of 8 attempts.

The delay between retries increases with a random factor. The average delays for 4 attempts are approximately 7, 45, and 300 seconds respectively, with a randomized variance of plus or minus 10%. These values may change without notice.

When Bloomreach encounters too many unrecoverable errors, it begins aborting webhook requests for customers it has not yet processed, to protect itself from exhaustion.

Unrecoverable errors

The following are considered unrecoverable errors:

• HTTP 4xx, except HTTP 429 Too Many Requests.
• Exhausting the number of retries for recoverable errors.
• Frequent connection issues.
• Repeated Jinja personalization rendering failures.

It's recommended to build your API to be idempotent, using a unique request identifier to reject duplicate requests.

Response format

Bloomreach supports any content type in requests. Only JSON and plain text can be parsed as a response. JSON formatted responses are recommended.

Performance requirements

Response time

Bloomreach expects your API to respond within 10 seconds (the default timeout). Latencies above 1 second degrade campaign performance and risk hitting the timeout limit. Aim to keep response times below 1 second. It's not true that Bloomreach retries requests with latencies above 1 second.

Concurrency

Bloomreach scenarios run in parallel by default. Your API should be able to handle at least 200 concurrent HTTP requests. You can configure the maximum number of parallel requests in each webhook. See webhook speed limits for details.

If needed, you can use HTTP 500 or connection reject to throttle concurrent requests, keeping the retry policy in mind.

Security

Authentication

HTTP Basic Authentication is supported natively. See RFC 2617 for details.

HTTPS

Your server must expose the API on a secure endpoint to ensure in-transit encryption. Bloomreach requires your server's SSL certificate to be signed by a trusted CA. The common name (CN) of the SSL certificate must match the API endpoint.

The current list of trusted CAs can be found here.

IP firewall allowlisting

You can limit the pool of outgoing IP addresses by enabling Use static IPs in the webhook configuration. The list of static IPs is shown there.

Note: Configuration of static IPs on instances other than app.exponea.com may differ.

Avoid overusing static IPs in webhook nodes

Using static IPs across a large number of webhooks can create bottlenecks and slow campaign execution across your entire Bloomreach instance.

As a general guideline, a few thousand API requests with static IPs is acceptable. More than 100,000 requests risks slower execution.

To avoid issues:

• Use HTTPS and an authorization header as your primary security measure instead of IP allowlisting.
• Where possible, call webhook API requests with static IPs in bulk to reduce the total number of campaign API requests.