How to use webhooks in Contentful

Web applications remain an important driving force of the digital age. One of the tools that developers, stakeholders, and end users can use to support their applications is the webhook, which virtually any web app can integrate to create dynamic and responsive content. 

In this guide, we explain what webhooks are and how to implement them in Contentful.

What are webhooks and how do they work?

Webhooks are event-driven automated messages sent from one application to another in real time. A webhook typically sends data, usually in JSON format, to a specified URL (known as the webhook endpoint) as soon as an event triggers it. 

Webhooks are unidirectional, so when application A sends data to application B, application B doesn't respond with data. Instead, it sends a minimal 200 response to show success, and is then responsible for processing the data itself. 

Let's take the example of a content management system (CMS), where you can update different fields and then click a button to publish your new page. You can configure a webhook so that when the "publish" event occurs (i.e., when the publish button is clicked), this triggers a specific endpoint in your application code, which in turn calls some code that rebuilds your application so it continues to mirror your CMS.   

How webhooks are different from APIs

The one-way nature of webhooks differentiates them from many other communication systems, such as APIs. Though webhooks serve much of the same purpose as APIs, they’re less resource intensive and more efficient when you need to feed information somewhere asynchronously. 

APIs require both a request and a response, adding latency and possibly resulting in the need to poll for data with constant checks. In contrast, using webhooks eliminates the need to constantly check for new data. Instead, whenever a specific event occurs, the sender triggers a webhook call, which automatically notifies the receiving system. The efficiency savings become even greater when a sender needs to send data to multiple clients at once, as this avoids multiple systems polling the sender for updates.

Configuring a webhook

Configuring a webhook involves letting the sender know when, where, and how to send the data. For this, it needs to know which events should trigger the webhook, what URL the data should be sent to, and what security (e.g., authentication tokens, secret keys) should be used.

Later in this article, we'll walk you through an example of how to configure a webhook in Contentful, so that specific events in the CMS (like new content being created) could trigger a rebuild of your site by calling an endpoint in your application code.

Use cases for webhooks

The use cases for webhooks primarily depend on what you want to achieve with your application. There are several ways you can use webhooks creatively to meet your goals. For example, with webhooks, you can have an application listen for database changes for a user’s profile completion and then have that application send an email to the user with welcome information, next steps, and so on. Additionally, you can integrate applications — such as Jira, Bitbucket, or a calendar application — with your messaging platform to enable receiving real-time updates. 

Benefits of webhooks

Webhooks were designed as an alternative to API polling, where a client periodically sends requests to a server to check for new data or updates. Webhooks offer two advantages over this method:

Greater efficiency: Webhooks only send data when something has changed (i.e., whenever an event has occurred), whereas API polling involves multiple unnecessary requests and can waste resources.

Real-time notifications: Webhook actions are triggered in real time, which gives you faster and more responsive workflows.

Challenges with using webhooks

Despite the clear advantages of webhooks, they present challenges that you need to resolve in order to ensure the security and integrity of your implementation.

Security risks: Since webhooks can involve external HTTP requests, this can lead to them being vulnerable to unauthorized access or malicious attacks. Mitigate these risks by implementing security measures such as HTTPS, signature verification, and authentication tokens.

Failure handling: Network issues or server downtime can sometimes lead to webhook delivery failures. Add robust error handling and retry mechanisms to your app to ensure data consistency and reliability.

Webhooks in Contentful explained

The one-way communication webhooks provide is ideal for a headless CMS like Contentful. Webhooks in Contentful enable updates to flow in real time, as any change occurring within the system can trigger a webhook. The webhook then sends information about these changes or updates to any number of systems, which you decide when configuring the webhooks.

This low-latency architecture provides much faster communication than a similar API-driven system, ensuring that any change to content within the system is immediately reflected in all connected systems.

Most webhooks in Contentful are triggered when either the data, the content model, or the content state undergoes a change. As a result, any sites or apps listening for that webhook immediately know they need to update. These functionalities provide the possibility of triggering an update event for users, or the rebuilding of your Next.js or Gatsby static website. 

Contentful provides a framework for creating webhooks based on five different types of content events: ContentType, Entry, Asset, Task, and Release. Each of these supports a variety of actions. For example, for an Entry webhook, Contentful supports all potential actions: create, save, auto_save, archive, unarchive, publish, unpublish, and delete.

The table below displays the capabilities of each content event:

In addition to the content events mentioned in the table, Contentful also offers some proprietary action events for release actions, bulk actions, and scheduled actions. Let’s explore each one of these and how you can use them. 

Webhooks for release actions

A release is a way to group multiple pieces of content together in Contentful, so they can be managed together. For example, if you want to publish a series of blog posts together, or if your ecommerce business is having a sales event and you want to publish all the spotlighted sale items together, you can create a release and add the relevant content to the release.

A release action is an action that's done to every item in the release — for example, to publish or unpublish all the items together. Release action webhooks can then listen for the release event — in this case, the publish and unpublish activities. 

Once you've created a release in Contentful, you can create a webhook for that release action. When the release is created or executed (e.g., published/unpublished), Contentful sends a webhook request to the configured URL, which you should configure to point at an endpoint in your own system. Your system can then receive the webhook request and take action, such as triggering a rebuild of your marketing website.

Webhooks for bulk actions

Bulk actions can be especially useful when the data your application displays to the end user is constantly changing and your headless application needs to consistently remain updated to provide the best user experience. As with release action webhooks, Contentful supports create and execute actions with this bulk action webhook. 

Returning to the example of the hypothetical ecommerce site, assume you intend to provide discounts on certain products according to the day. For this situation, you can create bulk actions that publish new products at the end of each day and unpublish the previous day’s discounted items. 

By listening to bulk action webhooks, you can know precisely when the bulk action executes and can then trigger a build accordingly. Therefore, this type of webhook is extremely beneficial for any site that displays frequently updated dynamic content. 

Webhooks for scheduled actions

Unlike bulk action and release action webhooks, scheduled actions expose webhooks for the create, save, execute, and delete event types. These webhooks can be beneficial for performing such steps as creating a build or running a search after setting up a scheduled action for your content. 

How to implement webhooks in Contentful

In this section, we’ll explain how to implement webhooks in Contentful using both the dashboard and the Contentful API. 

Using the Contentful dashboard

Contentful’s dashboard interface makes it easy to create webhooks, regardless of your level of expertise.  

Begin by logging into your account. Then click on the Settings dropdown on the upper navigation bar, as shown below, and then select Webhooks to navigate to the Webhooks dashboard:

In the Webhooks dashboard, you’ll see a list of already created webhooks (if you have any), a button labeled + Add Webhook toward the upper-right corner of the page. If you're creating a webhook for CI/CD integration purposes, there is also a Template tab that gives several webhook template options for CI/CD providers, such as CircleCI, Vercel or Netlify.

For now, click the + Add Webhook button to open the form, as shown below.

The form requires a name and URL for the webhook. Next, you can specify which events should trigger your webhook. By default, it will be triggered by all events. If you want to change this, click the radio button next to Select specific triggering events to see the checkbox selections for the events and types that you want this webhook to listen for. The disabled checkboxes represent the events that Contentful does not support for the given action type. 

After the Triggers section, there’s an option to add filters to the webhook. It offers a variety of selections to compare, such as Environment ID, Content Type ID, Entity ID, User ID (created by), User ID (updated by), and logical comparisons using equal, not equal, in, not in, regexp, and not regexp. Note that you can have more than one filter per webhook, which enables more complex conditions.

After the Filters, you can set the Headers, Content type, Content length, and Payload. 

The Payload functionality provides the ability to alter the webhook’s format to match your application’s structure. This can save considerable time. 

After filling in the custom payload in JSON format, click Save. You’ve now created a webhook that you can view in the Webhooks dashboard. 

You now know how to create a webhook and add a filter using the Contentful graphical user interface (GUI). It's also possible to do this using the Contentful API.   

Get started using webhooks today

Using webhooks with your application will add real-time communication between services, which will lead to faster updates and fewer resources being wasted. Now that you understand what webhooks are and how to implement them effectively, you can probably already think of some ways they could be used in your application.

For ecommerce sites, webhooks are often used to keep users aware of the different shipping stages that parcels are at. When managing a blog, they can be used to push updates to a variety of platforms or social media sites at once, and when doing CI/CD, webhooks allow automated tests to be triggered when code is committed to a repository.

If you're already using Contentful, you could use the Contentful-specific webhooks for static site generation — triggering a build to your static site once content has been published. Or, you could improve your site's search capabilities by triggering a script that regenerates index files whenever content is updated. Another use of webhooks that many of our users like is to send a notification to stakeholders once certain tasks have been completed. 

Contentful offers two ways to create webhooks, using the API and the GUI, providing a balance of flexibility and function. Sign up for a free Contentful account and see how our market-leading content platform can support your project or business.

Start building

Sign up for a free Contentful account

Use your favorite tech stack, language, and framework of your choice.

Subscribe for updates

Build better digital experiences with Contentful updates direct to your inbox.