Using webhooks for automatic updates

In this tutorial, you'll see how webhooks allow you to integrate Kentico Cloud with other software applications and automate your processes. Think of webhooks as programmatic notifications that let your application know when something changes inside your Kentico Cloud project.

Table of contents

As an example of webhooks in action, when a new content item is published your application can automatically react in numerous ways, such as:

Invalidating the cache of your app to make sure users see the latest content.

Updating a search index of your project's content.

Triggering a new build process and redeploying your application.

Notifying your team by sending an email, posting a message to a Slack channel or moving a card inside Trello.

Scheduling a social media post featuring the newly published content item.

Note: Updates to content made using the Content Management API can't trigger webhooks. The CM API can only work with content that is not published.

Receiving notifications

Once the webhook is registered, we will start sending HTTP POST notifications to the provided webhook URL. Receiving your notifications might take a few minutes or possibly even longer.

Note that the notifications may sometimes come in batches because the content changes are processed dynamically based on load.

Webhook call model

The notifications come in the form of a JSON object with two attributes: {~message~} and {~data~}. {~message~} tells you why the notification came and {~data~} tells you which content items and taxonomy groups were affected.

Verifying notifications

To verify the authenticity of the notifications, you need to generate a hash using the body of the notification and the secret key (you'll find the key in the configuration details of your webhook).

The calculated hash should match the notification signature in the {~X-KC-Signature~} header that is sent with each notification. For example, a signature can look like this {~fRbrQ1lpBSRB9T3MckJ51HDdjQ8UuV3WnjqKqirSpW8=~}. The signature is a base64 encoded string generated using a hash-based message authentication code (HMAC) with SHA-256.

For more examples on generating verification hashes, see the code samples in our API reference.

Once you have received and verified the message, you can react to it and use the provided information. You might consider using webhooks for clearing the cache of your app, triggering a build process, or scheduling social media posts. See our blog posts for some inspiration.

Worked examples

Learn how to integrate webhooks into your app's workflow from worked examples in our blog posts.

Getting the latest content

After you get a notification about changed content, you might want to explicitly request the new content from the Delivery API. You can do this by sending a standard request to the Delivery API with the X-KC-Wait-For-Loading-New-Content header.

Including the header will cause the Delivery API to explicitly fetch new content. Without the header, the Delivery API might return stale content (if cached by the CDN) for performance reasons while fetching latest content. To find out more, see Serving stale content in the Fastly documentation.

Retry policy

If your application responds with a {~20X~} HTTP status code, the notification delivery is considered successful. Any other status code or a request timeout (which occurs after 60 seconds) will result in a retry policy.

On the first unsuccessful delivery, we will try to send the notification again in 1 minute. If the delivery is unsuccessful, the delay between resending the notification increases exponentially to a maximum of 1 hour. The specific delay intervals are (in minutes): {~1~}, {~2~}, {~4~}, {~8~}, {~16~}, {~32~}, {~60~}. When the delay reaches 60 minutes, we try to deliver the notification every hour for up to 3 days, after which the notification is removed from the queue.

Email notifications

We will send email notifications to users with the Manage APIs capability in these cases:

Notification delivery repeatedly failing for 1 hour. This email is sent only once for each registered webhook.

Notification delivery repeatedly failing for 3 days. Note that we will not attempt to deliver the notification again.

Notification delivery was successful after failed attempts. This email is only sent if you previously received an email notification about a failed delivery.

Note: All notifications are delivered in the order they were created. For example, if a notification is successfully delivered after 4 minutes, the notifications created after it will follow in the original order.

Debugging webhooks

If you get an email that a webhook is failing, you might want to know more about that webhook and what the problem is. For that, you can find more information inside Kentico Cloud in your list of webhooks under Project settings -> Webhooks.

For an overview of the health of your webhooks, each webhook in your list has a colored status next to its name:

Light grey – Ready for message. This appears for newly created webhooks before any change to published content has been made (so no notification has been sent).

Green – Working. This appears for webhooks that have properly delivered notifications.

Red – Failing. This appears for webhooks that have not been delivered properly (received a response other than a {~20X~} HTTP status code). These webhook notifications are still being sent based on the retry policy.

Grey – Dead. This appears for webhooks where delivery has repeatedly failed and the retry policy has been exhausted so no more notifications will be sent.

For more information about each webhook, click on Debugging. You'll find a list of all notifications with attempts at sending within the last 3 days sorted from newest to oldest. You can filter the list to show everything, only failures (at any time in sending the message), or only active failures (where the last response was a failure). Click Refresh to reload the list.

Each notification in the list will show:

How many times the delivery has been attempted

A button ({@icon-code@}) to see the most recent response

The date and time when the most recent delivery attempt was made

A button ({@icon-code@}) to see the content of the sent notification with the chance to copy it

What's next?

Need help integrating webhooks into your project? Ask the community in Stack Overflow.