HomeEngagementContentDiscoveryOther Resources

Create a Webhook

Create a webhook to call an external API whenever a document is published.

Suggest Edits

Introduction

Goal

Create a webhook to call an external API whenever a document is published.

Prerequisites

Before starting:

To perform the Webhook Management API request in this tutorial, it is recommended to use the Postman collection for the Webhook Management API. However, you can use any other method or tool you like, such as curl or httpies.

Summary

In this tutorial, you'll use the Webhook Management API to configure a custom webhook in your Content environment that calls an external API whenever a document is published.

Configure a Webhook

Set up a Mock External REST Endpoint

Before you can set up the webhook in Content, you must have an external REST endpoint for the webhook to call when it's triggered. It's useful to start with a mock endpoint. In this tutorial. you'll use Webhook.site, a free service made for this exact purpose.

Navigate your browser to https://webhook.site/. You'll automatically get assigned a mock REST endpoint. Its URL will look similar to the one below:

https://webhook.site/f5ad315d-fc4e-4133-b20f-7a6a3a27bdda

You can find it under Your unique URL:

Create a Webhook Configuration

Use a POST request to the configurations endpoint of the Webhook Management API to configure a new webhook:

POST https://<your_content_account>.bloomreach.io/management/webhooks/v1/configurations

Use the following request body, substituting the url value with your webhook.site URL:

{
    "name": "Document publish",
    "enabled": true,
    "url": "https://webhook.site/f5ad315d-fc4e-4133-b20f-7a6a3a27bdda",
    "method": "POST",
    "triggers": [
        "document:publish"
    ],
    "headers": [
        {
            "name": "Content-Type",
            "value": "application/json",
            "secret": false
        }
    ]
}

The above configuration creates a webhook that is triggered by any document:publish event and will make a POST request to the specified url.

Test the Webhook

Log in to your Content environment, navigate to a document in the Content app, edit it (or take it offline), and then publish it.

Your new webhook should be triggered by the publication of the document and subsequently send a POST request to your Webhook.site endpoint. You can find the request's details, headers, and body in Webhook.site:

Note that the request body contains the time the webhook was triggered, the trigger (document:publish), as well as the identifier and path of the document that was published.

If you don't see the request show up in Webhook.site, use the executions endpoint of the Webhook Management API to check if the webhook was executed and, if so, what went wrong:

GET https://<your_content_account>.bloomreach.io/management/webhooks/v1/executions

A successful execution would look similar to this:

[
    {
        "id": "3eb06e3b-0469-498c-bd79-ff456e0e74f5",
        "payloadOperationId": "0e1afda1-ed4e-49e2-a5a7-0b15fc9705d4",
        "webhookConfigurationId": "69281adb-9de6-44d9-9039-ba73f0a1741a",
        "time": "2024-03-26T22:24:13.787Z",
        "status": "SUCCESS",
        "error": null,
        "requestDetail": "POST https://webhook.site/f5ad315d-fc4e-4133-b20f-7a6a3a27bdda {\"operationId\":\"0e1afda1-ed4e-49e2-a5a7-0b15fc9705d4\",\"time\":\"2024-03-26T23:24:13.188+01:00\",\"trigger\":\"document:publish\",\"entity\":{\"identifier\":\"d8d3a827-3dee-43fb-8098-d050d2883c9e\",\"path\":\"/content/documents/reference-spa/content/articles/top-tools-for-the-diyer-on-your-gift-list\"}}",
        "responseDetail": "200 OK This URL has no default content configured. <a href=\"https://webhook.site/#!/view/f5ad315d-fc4e-4133-b20f-7a6a3a27bdda\">View in Webhook.site</a>."
    }
]

If the execution was unsuccessful, status would be FAILURE and you may see, for example, a 404 Not Found response if the URL was incorrect.

Update a Webhook Configuration

If you need to update your webhook configuration, you'll need its webhookConfigurationId. You can get it from the executions endpoint's response above, or, alternatively, you can get all webhook configurations as follows:

GET https://<your_content_account>.bloomreach.io/management/webhooks/v1/configurations

The response will list all webhook configurations, including each webhook's id:

[
    {
        "id": "69281adb-9de6-44d9-9039-ba73f0a1741a",
        "name": "Document publish",
        "enabled": true,
        "triggers": [
            "document:publish"
        ],
        "system": {
            "createdBy": "[email protected]",
            "createdAt": "2024-03-26T23:17:08.079+01:00",
            "updatedBy": "[email protected]",
            "updatedAt": "2024-03-26T23:40:11.541+01:00"
        }
    }
]

Using your webhook's id, send a PUT request to the configurations endpoint to update your webhook. For example:

PUT https://<your_content_account>.bloomreach.io/management/webhooks/v1/configurations/69281adb-9de6-44d9-9039-ba73f0a1741a

Use the same request body format as when you created the webhook configuration:

{
    "name": "Document publish",
    "enabled": true,
    "url": "https://webhook.site/f5ad315d-fc4e-4133-b20f-7a6a3a27bdda",
    "method": "POST",
    "triggers": [
        "document:publish"
    ],
    "headers": [
        {
            "name": "Content-Type",
            "value": "application/json",
            "secret": false
        }
    ]
}

Next Steps

Implement External Endpoint

Now that the webhook is in place, you can implement the external endpoint to respond to the webhook's call and do something with the information provided in the request body.

Update your webhook configuration to replace the mock endpoint URL with the one you implemented.

Configure More Webhooks

You can use this tutorial as a template to add more webhooks for any other supported trigger event:

  • document:publish
  • document:unpublish
  • page:publish
  • page:unpublish

Updated about 1 month ago