Webhooks are HTTP callbacks which can be used to send notifications when data in Contentful is changed, allowing external systems to react to changes to do things such as trigger a website rebuild or send a notification to a chat application.
You can view a webhook payload in an entity JSON object. To view an entity JSON object for:
- Content type - Open the JSON Preview in the content type editor.
- Entry - An entry JSON can be previewed with the JSON Viewer app.
Environment aliases and webhooks
Webhooks can be triggered for an environment alias using the
filters property of a
webhook just like environments. Webhooks only trigger for a given environment alias if it is used via that alias. Example: for a webhook set to trigger on the
master environment alias only
PUT spaces/<space-id>/entries/my-blog-postwould trigger the webhook
PUT spaces/<space-id>/environments/master/entries/my-blog-postwould trigger the webhook
PUT spaces/<space-id>/environments/environment-to-serve/entries/my-blog-postwould not trigger the webhook
Please refer to the webhooks reference for more details.
You can also set up webhooks to fire on environment alias events. For example, when an alias is created, updated or deleted.
Filtering of webhooks
Sometimes it is necessary to filter webhooks based on the properties of the entity that triggered the webhook. The most common examples are:
- filter webhooks by environment ID (e.g. only trigger the pre-release test suite on a CI service for the environment with ID
- filter webhooks by entity ID (e.g. only trigger for a specific entry, asset or content type ID)
- filter webhooks by content type ID (e.g. only trigger for entries of a specific content type ID)
false and not trigger the webhook. E.g. a webhook for topics
Asset.publish filters on a specific content type ID. As assets don't have a content type, all webhooks which are triggered by
Asset.publish will be muted by the filter.
The Contentful web application automatically saves changes in all documents you are working on. Contentful considers documents edited in the last 5 seconds as active and uses that information to call the webhook integrations you have configured.
If you edit an entry in the web app for one minute, and you have a webhook configured to be called for
auto_save actions, the defined webhook will be sent 12 times (60 seconds divided by 5 seconds).
When you call the
sdk.entry.save() method provided by the App SDK an
auto_save webhook is sent.
If you update an entry or asset via the Content Management API or an App the
save webhook is sent.
Customizing webhook calls
By default every webhook call:
- uses the HTTP
- has the
Content-Typeheader set to
- sends a predefined body depending on the triggering event
If you want to change any of the aforementioned webhook properties you can use a mechanism called "webhook transformation". Navigate to the CMA reference for more details. All customizable properties can be set with both the API and the web app.
Webhook requests will timeout if the recipient server does not respond within a maximum of 30 seconds. A webhook request that times out will be considered failed and be retried according to the retry policy. Because of this, it is recommended that processing of webhooks be done asynchronously.
For local testing we recommend to use webhook.site to inspect the sent webhooks or ngrok to build webhook consumers on your developer machine. ngrok also provides a guide on how to use ngrok to integrate your localhost app with Contentful by using Webhooks.
- Tools and libraries to make your Contentful experience better
- Webhooks API tutorials guide
- Learn more about how to extend Contentful in our Learning Center
Not what you’re looking for? Try our FAQ.