Webhooks

A webhook is a user-defined HTTP callback. It is a mechanism that sends real-time information to any third-party app or service. As a result, it becomes easy to keep your application in sync with your Contentstack account.

Webhooks allow you to specify a URL to which you would like Contentstack to post data when an event happens. So, for instance, if you want to be notified every time a new entry is created in a content type, you can create a webhook for it. You can add webhooks for almost all the events in Contentstack.

Webhook Events

Here's a complete list of events available for Webhooks.

Content Type

Entries

Assets

Releases

When a webhook is triggered for an entry or asset, because it was published/unpublished via a release, the webhook data of such as an event contains a 'source' key. This key contains the JSON data of the release (type, title, and UID) it was deployed through.

This is useful in cases where a lot depends on the webhook data. For example, in the case of static site generators, a build is generated every time an item (entry or asset) is published or unpublished. So, if a release is deployed with 200 items, it will generate a build 200 times, instead of just one time for the release. To avoid such cases, the developer can write custom code that ignores events whose response contains the source key. So, only one build will be generated for the whole release.

Create a Webhook

To create a webhook, go to Settings > Webhooks and click on 'Let’s go make one!' or the '+ New Webhook' link at the top-right side of the page.

On the webhook configuration page, you will see some fields that you can use to set up a webhook.

First, enter a suitable ‘Name’ for the webhook. In the 'URL to notify' field, specify the URL or web address where the data will be sent once the webhook is triggered. The URL will receive an HTTP POST request when the selected event happens.

You can also set up basic auth for securing the webhook. To do this, enter values in the 'HTTP basic auth username' and the 'HTTP basic auth password' fields. The 'Custom headers' field lets you pass any additional details, if required, with the content. You can add multiple headers by clicking the '+' link.

Finally, under 'When,' set the conditions for the webhook. Here, you need to define the event when the webhook will be triggered. For ease of use, we have two views under it: 'Conditional View' and 'Code View'.

Now, let’s understand how to create a new webhook with the help of an example. Let us create a webhook that will be triggered whenever any changes are made to any content type in a stack.

Note: A webhook will not trigger on local environments such as localhost.

Tutorial Video

Now, let's look at how to create a webhook.

Edit a Webhook

You can edit an existing webhook at any time. To do so, perform the steps given below:

1. Click on the webhook that you want to edit.
2. Make the necessary changes to the configuration fields available under Details.
3. Click on Save to save the changes made to the webhook.

Delete a Webhook

To delete a webhook, perform the steps given below:

1. Hover over the webhook that you want to delete. On the extreme right side, you will notice a 'More Options' icon (or three vertical dots).
2. Click on this icon and select 'Delete'.

Export a Webhook

To export a webhook, we have two methods.

Method 1

1. Hover over the webhook that you want to export. On the extreme right side, you will notice a 'More Options' icon (or three vertical dots).
2. Click on this icon and select Export.

Method 2

If you have opened the webhook that you want to export, click on the Export button available on the bottom-right corner of the webhook page.

This will download the JSON file of the webhook into your local storage system.

Import a Webhook

You can create a new webhook or update an existing webhook by importing a JSON file with the webhook data.

Import a new webhook

Perform the steps given below:

1. Create a new webhook by navigating to Settings > Webhooks and click on Let’s go make one! or the + New Webhook link at the top-right side of the page.
2. On the webhook configuration page, click on the Import button available on the bottom-right corner of the page.
3. Click on Browse and select the appropriate JSON file.
4. Click on Import.

Update a webhook by importing JSON file

Open the webhook that you need to update, and click on the Import button available on the top-right corner of the webhook page.

View Webhook Logs

Contentstack keeps a log of all the triggered webhooks. To view the log, go to Settings > Webhooks. Then, click on the webhook of which you wish to view the log.

On the page that appears, you will see two tabs: 'Details' and 'Logs'. The 'Details' tab lets you view/edit the webhook settings, while the 'Logs' tab displays the log of the webhook. Click the 'Logs' tab for more information.

Here, under 'Webhook Called At,' you will see the last time when the webhook was triggered. While the display time is in humanized format (for example, 3 days ago), you can get the actual triggered time by hovering on the displayed time.

Under 'Call Status,' you will get the result/status of the webhook. HTTP 200 denotes success, while on a failed attempt (if the webhook status codes are 4xx and 5xx i.e., non 2xx), the message displayed will depend on the failure. In case of a failure or if a session timeout occurs (webhook request timeout is 30 seconds), the webhook will immediately retry to send data to the destination URL again for two more times. After three unsuccessful attempts, the webhook will not make any further attempts automatically. However, you can trigger the webhook manually at any time by clicking the 'Retry' link.

To view the details of the webhook call, click the 'Call Details' link. It will display the request details of the webhook call as well as the response received. In the case of failed attempts, the 'Complete response' section will displayno data.

Webhook Data Format

When a webhook is triggered, the data received is in the following format:

Method: POST
Headers: "Content-Type: application/json", "Contentstack-Signature:9876543210"
Body: {
  "event": "string",
  "module": "string",
  "api_key": "string",
  "data": "object"
}

Details of the POST call's 'Body' keys:

event

One of these [create, update, delete, publish, publish.start, publish.success, publish.fail, unpublish, unpublish.start, unpublish.success, unpublish.fail]

module

One of these [content types, entry, asset, release]

api_key

The API key of the stack

data

Response object

Examples

Here’s an example of a response object attached to the POST body when trying to update an existing entry in a content type.

{
  "module": "entry",
  "api_key": "blt22222e2222222222",
  "data": {
    "entry": {
      "title": "Webhook Entry",
      "url": "/webhook-entry",
      "locale": "en-us",
      "uid": "bltfe99999fa999b9a9",
      "created_by": "bltcb333333df3d3333",
      "updated_by": "bltcb333333df3d3333",
      "created_at": "2019-03-08T08:57:47.737Z",
      "updated_at": "2019-03-08T08:58:07.560Z",
      "ACL": {},
      "_version": 2,
      "tags": []
    },
    "content_type": {
      "created_at": "2019-03-08T08:57:38.993Z",
      "created_by": "bltcb333333df3d3333",
      "updated_at": "2019-03-08T08:57:38.993Z",
      "updated_by": "bltcb333333df3d3333",
      "title": "Webhook created",
      "uid": "webhookcreated",
      "description": "",
      "schema": [
        {
          "display_name": "Title",
          "uid": "title",
          "data_type": "text",
          "field_metadata": {
            "_default": true
          },
          "unique": true,
          "mandatory": true,
          "multiple": false
        },
        {
          "display_name": "Webhook created",
          "uid": "url",
          "data_type": "text",
          "field_metadata": {
            "_default": true
          },
          "unique": false,
          "mandatory": false,
          "multiple": false
        }
      ],
      "options": {
        "title": "title",
        "singleton": false,
        "publishable": true,
        "is_page": true,
        "sub_title": [],
        "url_pattern": "/:title",
        "url_prefix": "/"
      }
    }
  },
  "event": "update",
  "triggered_at": "2019-03-08T08:58:07.725Z"
}

Here’s an example of a response object attached to the POST body when an asset is published successfully on an environment.

{
  "module": "asset",
  "api_key": "blt22222e2222222222",
  "data": {
    "asset": {
      "uid": "blt1c1eb111111a1d11",
      "created_at": "2019-03-08T09:04:25.377Z",
      "updated_at": "2019-03-08T09:04:25.377Z",
      "created_by": "bltcb222222df2d2222",
      "updated_by": "bltcb222222df2d2222",
      "content_type": "image/png",
      "file_size": "560",
      "tags": [],
      "filename": "image.png",
      "url": "your_asset_URL",
      "ACL": {},
      "is_dir": false,
      "parent_uid": null,
      "_version": 1,
      "title": "image.png",
      "description": "",
      "publish_details": [
        {
          "environment": "blt3c3b333ae3333333",
          "locale": "en-us",
          "time": "2019-03-08T09:04:43.921Z",
          "user": "bltcb222222df2d2222",
          "version": 1
        }
      ]
    },
    "environment": {
      "name": "blank",
      "servers": [],
      "urls": [],
      "deploy_content": false,
      "uid": "blt5c5b555ae5555555",
      "created_by": "bltcb222222df2d2222",
      "updated_by": "bltcb222222df2d2222",
      "created_at": "2019-03-08T08:53:46.157Z",
      "updated_at": "2019-03-08T08:53:46.157Z",
      "ACL": [],
      "_version": 1
    },
    "action": "publish",
    "status": "success",
    "locale": "en-us"
  },
  "event": "publish",
  "triggered_at": "2019-03-08T09:04:53.444Z"
}

Here's an example of a response object attached to the POST body when an entry is published successfully on an environment

{
    "event": "publish",
    "source": {
        "type": "release"
        "title": "Release01",
        "uid": "blt2f22e2222222e111"
    },
    "data": {
        "entry": {
            ...
        }
    },
    "api_key": "blt3333d3ad333beedc",
    "module": "entry",
    "triggered_at": "2019-03-06T05:34:44.876Z"
}

Here's an example of a response object attached to the POST body when an asset is published successfully on an environment

{
    "event": "publish",
    "source": {
        "type": "release"
        "title": "Release02",
        "uid": "blt2f22e2222222e111"
    },
    "data": {
        "asset": {
            ...
        }
    },
    "api_key": "blt3333d3ad333beedc",
    "module": "asset",
    "triggered_at": "2019-03-06T05:34:44.876Z"
}

Lastly, here's an example of a response object attached to the POST body when a release has been deployed successfully.

{
  "module": "release",
  "api_key": "blt111c11e111111b11",
  "data": {
    "release": {
      "name": "Webhook-Release",
      "description": "Release 08-03-2019",
      "locked": true,
      "items": [
        {
          "uid": "bltf0df0ea0a0000001",
          "version": 1,
          "action": "publish",
          "content_type_uid": "content_type",
          "locale": "en-us",
          "title": "Entry1"
        },
        {
          "uid": "bltf0df0ea0a0000002",
          "version": 1,
          "action": "publish",
          "content_type_uid": "content_type",
          "locale": "en-us",
          "title": "Entry2"
        },
        {
          "uid": "bltf0df0ea0a0000333",
          "version": 1,
          "action": "publish",
          "content_type_uid": "built_io_upload",
          "locale": "en-us",
          "title": "Image1.png"
        },
        {
          "uid": "bltf0df0ea0a0000444",
          "version": 1,
          "action": "publish",
          "content_type_uid": "built_io_upload",
          "locale": "en-us",
          "title": "Image2.png"
        }
      ],
      "uid": "blt2f22e2222222e111",
      "created_by": "blt123cdeced1231e23",
      "updated_by": "blt123cdeced1231e23",
      "created_at": "2019-03-08T09:25:24.165Z",
      "updated_at": "2019-03-08T09:25:32.278Z",
      "status": [
        {
          "environment": "blt3c333333c33d3a33",
          "time": "2019-03-08T09:25:32.235Z",
          "status": "success",
          "user": "blt123cdeced1231e23"
        }
      ]
    },
    "environment": {
      "deploy_content": false,
      "servers": [],
      "urls": [
        {
          "url": "",
          "locale": "en-us"
        }
      ],
      "name": "production",
      "uid": "blt3c333333c33d3a33",
      "created_by": "blt123cdeced1231e23",
      "updated_by": "blt123cdeced1231e23",
      "created_at": "2019-03-08T09:22:35.779Z",
      "updated_at": "2019-03-08T09:22:35.779Z",
      "ACL": [],
      "_version": 1
    },
    "action": "deploy",
    "status": "success"
  },
  "event": "deploy",
  "triggered_at": "2019-03-08T09:25:32.518Z"
}

Secure Your Webhooks

Webhooks are an ideal way to send information automatically to an external application. However, it is critical to ensure that the receiving app or server validates the source before accepting requests. To avoid potential security threats, users can secure your webhooks.

Contentstack offers two highly recommended security measures that you can implement when setting up a webhook. These are 'Basic Authentication' and 'Custom Headers'.

Let’s look at the two ways that can be used to secure your webhook event data.

Note: Currently, Contentstack uses dynamic IP addresses for webhook events. So, you need to secure your webhooks using either 'Basic Authentication' or 'Custom Headers' security measures. It's recommended that you avoid using the hash signature, X-Contentstack-Signature, as it has been deprecated.

Basic authentication

When setting up a webhook, Basic Authentication, i.e., Basic Auth, allows users to set a username and password associated with your HTTP endpoint. With this method, your basic auth field values are included in the header of the HTTP request.

To set this method, go to SETTING > Webhooks. Here, you can add the basic auth details by providing the values for the following fields:

• HTTP basic auth username
• HTTP basic auth password

Now, your URL is secure with the above basic auth username and password.

Custom Headers

As an additional method of security, you can specify custom headers that Contentstack will use while sending the payload to the specified endpoint. Custom Headers give the destination application an option to authenticate your webhook requests, and reject any that do not contain these custom headers.

Custom headers are key-value parameters that you send/receive in the header of each call of your notifying URL.

To set this method, go to SETTING >; Webhooks. Here, you can add custom headers by providing the values for the following fields under ‘Custom headers’:

• Key
• Value

Note: You can set multiple custom header key-value pairs.