Webhooks extend integration possibilities by notifying you, another person or system when resources have changed by calling a pre-configured HTTP endpoint.

When webhooks are called

Webhooks are called as the result of an action against assets, entries or content types. Whenever a matching event occurs, a webhook calls a specified URI to react. For example, every time a user edits an entry, send a push notification or message to a Slack channel.

The following table summarizes the actions that Contentful offers for every resource type:

Create and configure a webhook

With the web app

In the top navigation bar, open Settings → Webhooks. Click Add webhook, configure the remote host, and click Save.

You can configure the events that trigger a webhook at the bottom of the screen.

With the API

Create a webhook by sending the settings for the webhook in a body with your API call, for example, the following:

curl -X POST "https://api.contentful.com/spaces/<SPACE_ID>/webhook_definitions"
  -d '{"url": "<URL>", "name": "foo", "topics": ["*.*"]}'
  -H 'Authorization: Bearer <API_KEY>'
  -H 'Content-Type: application/vnd.contentful.management.v1+json'

Will create a new webhook in the specified space with a url, name, and topics which match the configuration options mentioned above.

Topics

When creating a webhook you have to explicitly specify for which changes on your content (topics) you want your webhook called.

For example, your webhook could be called when:

• Any content (of any type) is published.
• Assets are deleted.

These filters have to be translated into a list of [Type].[Action] pairs, [*.publish, Asset.delete, Entry.*], and included in the payload that defines the webhook.

* is a wildcard character that can be used in place of any action or type. The combination *.* is also valid and means that your webhook is subscribed to all actions across all types.

List webhooks in a space

With the web app

The Webhooks overview screen shows a list of the most recent webhook calls made, their status, possible errors, and the target URL.

With the API

To list all webhooks in a space, use the following endpoint:

curl -X GET "https://api.contentful.com/spaces/<SPACE_ID>/webhook_definitions"
-H "Authorization: Bearer <API_KEY>"
-H "Content-Type: application/vnd.contentful.management.v1+json"

Find more details on listing the webhooks in a space with the API in our reference docs.

Activity log of a call

With the web app

Click the View details link of any webhook in the overview screen to get a detailed activity log, including the JSON and remote server response.

With the API

The following endpoint will return the status of recent calls made by a webhook and any errors.

curl -X GET "https://api.contentful.com/spaces/<SPACE_ID>/webhooks/<WEBHOOK_ID>/calls"
-H "Authorization: Bearer <API_KEY>"
-H "Content-Type: application/vnd.contentful.management.v1+json"

Find more details on getting the activity log of a webhook with the API in our reference docs.

Auto save

The Contentful web app automatically saves documents you are working on after every change you make. Contentful keeps track of documents active in the web app and uses that information to call webhooks you have configured. Contentful considers documents edited in the last 20 seconds as active.

This means that, if you are editing an entry in the web app for one minute, and you have a webhook configured to be called for auto_save actions, that webhook will be called 3 times.