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 wish to be notified every time a new entry is created in a content type, you can create a webhook for it. Webhooks can be created for almost all the events in Contentstack.

Webhook Events

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

Content Type

Entries

Assets

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 a number of 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, follow the steps given below:

1. Click on the webhook that you wish to modify.
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, follow the steps given below:

1. Hover over the webhook that you wish 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'.

View Webhook Logs

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

On the page that appears, you will see two tabs: 'Edit' and 'Logs'. The 'Details' tab lets you view/edit the webhook settings, while the 'Logs' tab display 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 humanized format time.

Under 'Call Status,' you will get the result/status of the webhook. HTTP 200 denotes success, while on a failed attempt, the message displayed will depend on the failure. In case of a failed attempt, the webhook will try to send data to the destination URL again after an interval (one minute). After five 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 case of failed attempts, no data will be displayed under 'Complete response'.

Webhook Data Format

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

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

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

event

Any one of [create, update, delete, publish, publish.start, publish.success, publish.fail, unpublish, unpublish.start, unpublish.success, unpublish.fail]

module

Any one of [content types, entry, asset]

site_api_key

The site's API key

data

Response object

Examples

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

{
  "event": "update",
  "module": "entry",
  "site_api_key": "blt123456789abcdefgh",
  "data": {
    "entry": {
      "updated_at": "2015-06-25T06:41:30.584Z",
      "created_at": "2015-06-24T13:38:22.227Z",
      "title": "my_edited_entry",
      "url": "/",
      "_metadata": {
        "uid": "1234567890abcdefgh",
        "locale": "en-us"
      },
      "tags": [],
      "updated_by": "qwertyuiopzxcvbnm1234567890",
      "created_by": "qwertyuiopzxcvbnm1234567890",
      "app_user_object_uid": "system",
      "published": true,
      "uid": "blt123456789abcdef",
      "_version": 3
    },
    "content types": {
      "uid": "aaaa",
      "schema": [
        {
        },
      ]
    }
  }
}

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

{
  "event": "publish.success",
  "module": "asset",
  "site_api_key": "blt1234567890abcdefgh",
  "data": {
    "asset": {
      "uid": "blt1234567890abcdef",
      "created_at": "2015-06-25T10:02:16.288Z",
      "updated_at": "2015-06-25T10:02:16.288Z",
      "created_by": "qwertyuiopzxcvbnm1234567890",
      "updated_by": "qwertyuiopzxcvbnm1234567890",
      "content_type": "image/jpeg",
      "file_size": "114998",
      "tags": [],
      "app_user_object_uid": "system",
      "filename": "my_test_file.jpg",
      "url": "https://example.com/1234567890qwertyuiopzxcvbnm/download",
      "_metadata": {
        "publish_details": [
          {
            "user": "qwertyuiopzxcvbnm1234567890",
            "time": "2015-06-25T10:45:34.113Z",
            "locale": "en-us",
            "environment": "blt123456asdfghjkl"
          }
        ]
      }
    },
    "environment": {
      "name": "development"
    }
  }
}

Secure Your Webhooks

Webhooks are an ideal way to send information automatically to an external application. However, it is important to ensure that the receiving app or server validates the source before accepting requests, in order to avoid potential security threats. This can be done by securing 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.

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. This gives the destination application an option to authenticate your webhook requests, and reject any other requests that do not contain these custom headers.

Custom headers are basically 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.