Webhooks

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:

Type/action Create Save Auto save Archive Unarchive Publish Unpublish Delete
Content type Yes Yes No No No Yes Yes Yes
Entry Yes Yes Yes Yes Yes Yes Yes Yes
Asset Yes Yes Yes Yes Yes Yes Yes Yes

Create and configure a webhook

With the web app

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

Creating a new webhook

Creating a new webhook

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

Configure triggering events

Select what events trigger the webhook

With the API

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

1
2
3
4
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.

Note: Using * allows your webhook to be called for future actions or types that didn't exist when the webhook was created or updated. Find more details on creating a webhook with the API in our reference docs.

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.

Overview of webhooks

With the API

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

1
2
3
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.

Activity log for webhooks

Detailed activity log of a webhook

With the API

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

1
2
3
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.