Webhook Management API

Introduction

The Webhook Management API enables Bloomreach Content developers to manage webhooks in a running Bloomreach Content environment. A REST endpoint is provided, via which webhook operations such as create, update, get, delete can be performed. Webhooks are used to do external API calls after defined events are triggered.

API Base URL

https://<your_brx_host>.bloomreach.io/management/webhooks/v1

Authorization

The Webhook Management API is a protected management API and requires authorization using a token. See API Authorization for instructions on how to obtain and use a token.

Updates and conflict prevention

When updating an existing webhook resource, you must include the entire resource including all its existing unchanged properties. It's not possible to update only a subset of properties. Read more about how to handle updates and conflict prevention.

Events

The following events can trigger a webhook call:

Document publish
Document unpublish
Page publish
Page unpublish

External API Requirements

For a webhook to be able to call an external API endpoint, it must meet the following requirements:

Provides HTTPS endpoint that can handle concurrent requests
HTTP 200 for success receiving
HTTP 400 for errors or invalid requests to notify Bloomreach Content not to retry the request
HTTP 500 to notify Bloomreach Content to retry the same request later*
Authenticates requests with HTTP authorization header (currently only with HTTP custom headers)

* Connection issues (timeout, reject, drop) also trigger retries

API Reference

Development Aids

To aid developers in working with the Webhook Management API, the following tools and resources are provided:

Tutorial

Follow this short tutorial to create your first webhook:

Create a Webhook

Public Environment

If you don't have access to a Bloomreach Content environment yet, you can use the Public Developer Environment. Follow the instructions to retrieve an authentication token and explore the APIs.

Run in Postman

Import the Project Management API collection and try the endpoints in Postman . The collection provides many examples of how the endpoints can be used.

Run in Postman

The only thing needed to use the Postman collection is to setup the environment variables:

brxHost: the URL of your Bloomreach Content environment
x-auth-token: the Authentication token