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.
Here's a complete list of events available for Webhooks.
Method | Description |
content_types.create | New content type is created |
content_types.update | Any content type is updated |
content_types.{contenttype_uid}.update | A specific content type is updated |
content_types.delete | Any content type is deleted |
content_types.{contenttype_uid}.delete | A specific content type is deleted |
Method | Description |
content_types.entries.create | Any entry is created |
content_types.{contenttype_uid}.entries.create |
An entry is created within a content type |
content_types.entries.update |
Any entry is updated |
content_types.{contenttype_uid}.entries.update | An entry from a specific content type is updated |
content_types.{contenttype_uid}.entries.{entry_uid}.update |
A specific entry of a specific content type is updated |
content_types.entries.publish |
Any entry is published |
content_types.entries.publish.fail | Any entry failed to publish |
content_types.entries.unpublish |
Any entry is unpublished |
content_types.entries.unpublish.fail | Any entry failed to unpublish |
content_types.entries.delete |
Any entry is deleted |
content_types.{contenttype_uid}.entries.delete | Any entry from a specific content type is deleted |
content_types.{contenttype_uid}.entries.{entry_uid}.delete |
A specific entry of a specific content type is deleted |
Method | Description |
assets.delete |
Any asset is deleted |
assets.{asset_uid}.delete |
A specific asset is deleted |
assets.publish |
Any asset is published |
assets.publish.fail | Any asset failed to publish |
assets.unpublish |
Any asset is unpublished |
assets.unpublish.fail | All assets failed to unpublish |
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.
Now, let's look at how to create a webhook.
You can edit an existing webhook at any time. To do so, follow the steps given below:
To delete a webhook, follow the steps given below:
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'.
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:
Any one of [create, update, delete, publish, publish.start, publish.success, publish.fail, unpublish, unpublish.start, unpublish.success, unpublish.fail]
Any one of [content types, entry, asset]
The site's API key
Response object
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" } } }
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.
Note: Currently, Contentstack uses dynamic IP addresses for webhook events. So, you need to secure your webhook using any of the mentioned security measures.
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:
Now, your URL is secure with the above basic auth username and password.
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’:
Note: You can set multiple custom header key-value pairs.