Webhooks

Webhooks provide real-time, event-driven communication within Umbraco. Seamlessly integrated, these lightweight, HTTP-based notifications empower you to trigger instant actions and synchronize data. With its different extension points, you can tailor these webhooks to fit a broad range of requirements.

Getting Started

To work with Webhooks, you need to go to Webhooks within the Settings section:

From here we can create a webhook, by clicking the Create webhook button, which will take you to the Create webhook screen:

Url

The Url should be the endpoint you want the webhook to send a request to, whenever a given Event is fired.

Events

Events are when a given action happens, by default there are 5 events you can choose from.

• Content Published - This event happens whenever some content gets published.

• Content Unpublished - This event happens whenever some content gets unpublished

• Content Deleted - This event happens whenever some content gets deleted.

• Media Deleted - This event happens whenever a media item is deleted.

• Media Saved - This event happens whenever a media item is saved.

Content type

If you have selected a Content or Media event, you can specify your preferences. You can choose to trigger your webhook only for a given Document or Media type.

For example, if you have selected Content Published event. You can then specify that you only want the webhook to fire, when the content is of a given content type.

Headers

You can specify custom headers, that will be sent with your request.

For example you could specify Accept: application/json, security headers, etc.

Defaults

Umbraco webhooks have been configured with some defaults, such as default headers or some events that send a payload. In this section, we will take a look at those.

Json payload

For example, the Content Published event will also send the given content that triggered the event. The json from is the same as the Content Delivery Api, an example of such a json object:

{
  "Name": "Root",
  "CreateDate": "2023-12-11T12:02:38.9979314",
  "UpdateDate": "2023-12-11T12:02:38.9979314",
  "Route": {
    "Path": "/",
    "StartItem": {
      "Id": "c1922956-7855-4fa0-8f2c-7af149a92135",
      "Path": "root"
    }
  },
  "Id": "c1922956-7855-4fa0-8f2c-7af149a92135",
  "ContentType": "root",
  "Properties": {}
}

however, the Content deleted does not send the entire content as JSON, instead, it sends the Id of the content like so:

{
  "Id": "c1922956-7855-4fa0-8f2c-7af149a92135"
}

Headers

By default, webhook requests will include 3 headers

• user-agent: Umbraco-Cms/{version}, where version is the current version of Umbraco.

• umb-webhook-retrycount: {number of retries}, where number of retries, is the current retry count for a given webhook request.

• umb-webhook-event: {Umbraco.event}, where event is the event that triggered the request, for example for Content published: umb-webhook-event: Umbraco.ContentUnpublish

Configuring Webhooks

Adding more events

To add more than the default events to Umbraco, you can leverage the provided IUmbracoBuilder and IComposer interfaces. Below is an example of how you can extend the list of available webhook events using a custom WebhookComposer:

using Umbraco.Cms.Core.Composing;

public class CustomWebhookComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.WebhookEvents()
            .Clear()
            .AddCms(cmsBuilder =>
            {
                // Add your custom events here
                cmsBuilder
                    .AddDefault()
                    .AddContent()
                    .AddContentType()
                    .AddDataType()
                    .AddDictionary()
                    .AddDomain()
                    .AddFile()
                    .AddHealthCheck()
                    .AddLanguage()
                    .AddMedia()
                    .AddMember()
                    .AddPackage()
                    .AddPublicAccess()
                    .AddRelation()
                    .AddRelationType()
                    .AddUser();
            });
    }
}

This is a list of all the current events that are available through Umbraco. If you want them all enabled, you can use the following:

builder.WebhookEvents().Clear().AddCms(false);

Replace Webhook Events

Sometimes it is desirable to modify one of the standard Umbraco webhooks, for example, to change the Payload. This can be done by adding a custom implementation, as shown in the code example below:

[WebhookEvent("Content Published", Constants.WebhookEvents.Types.Content)]
public class MyCustomContentPublishedWebhookEvent : WebhookEventContentBase<ContentPublishedNotification, IContent>
{
    private readonly IPublishedSnapshotAccessor _publishedSnapshotAccessor;
    private readonly IApiContentBuilder _apiContentBuilder;


    public MyCustomContentPublishedWebhookEvent(IWebhookFiringService webhookFiringService, IWebhookService webhookService, IOptionsMonitor<WebhookSettings> webhookSettings, IServerRoleAccessor serverRoleAccessor, IPublishedSnapshotAccessor publishedSnapshotAccessor, IApiContentBuilder apiContentBuilder) : base(webhookFiringService, webhookService, webhookSettings, serverRoleAccessor)
    {
        _publishedSnapshotAccessor = publishedSnapshotAccessor;
        _apiContentBuilder = apiContentBuilder;
    }

    public override string Alias => "Umbraco.ContentPublish";
    protected override IEnumerable<IContent> GetEntitiesFromNotification(ContentPublishedNotification notification) => notification.PublishedEntities;

    protected override object? ConvertEntityToRequestPayload(IContent entity)
    {
        if (_publishedSnapshotAccessor.TryGetPublishedSnapshot(out IPublishedSnapshot? publishedSnapshot) is false || publishedSnapshot!.Content is null)
        {
            return null;
        }

        IPublishedContent? publishedContent = publishedSnapshot.Content.GetById(entity.Key);

        return new
        {
            MyData = "Your data",
            PublishedContent = publishedContent is null ? null : _apiContentBuilder.Build(publishedContent)
        };
    }
}

Add the following line in a Composer to replace the standard Umbraco implementation with your custom implementation:

public class MyComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.WebhookEvents().Replace<ContentPublishedWebhookEvent, MyCustomContentPublishedWebhookEvent>();
    }
}

Webhook settings

Webhook settings can be configured in your appsettings.*.json and is in the Umbraco::CMS section, like so:

  "Umbraco": {
    "CMS": {
      "Webhook": {
        "Enabled": true,
        "MaximumRetries": 5,
        "Period": "00:00:10",
        "EnableLoggingCleanup": true,
        "KeepLogsForDays": 30
      }

• Enabled - Whether or not webhooks are enabled.

• MaximumRetries - How many retries a given webhook request will do.

• Period - The period to wait between checks of any webhook requests needing to be fired.

• EnableLoggingCleanup - Whether of not to enable webhook log cleanup.

• KeepLogsForDays - How many days to keep webhook logs for.

Introduction

With Umbraco, you can even create your own webhook events.

This documentation guides you through the process of implementing your own webhook events using the WebhookEventBase<TNotification> base class.

Creating an event with the WebhookEventBase

The WebhookEventBase<TNotification> class serves as the foundation for creating custom webhook events. Here's a brief overview of its key components:

• Alias: The property that must be overridden to provide a unique identifier for your webhook event.

• EventName: A property that represents the name of the event. It is automatically set based on the provided alias unless explicitly specified.

• EventType: A property that categorizes the event type. It defaults to "Others" but can be customized using the WebhookEventAttribute.

• WebhookSettings: The property containing the current webhook settings.

• ProcessWebhooks: The method responsible for processing webhooks for a given notification.

• ShouldFireWebhookForNotification: The method determining whether webhooks should be fired for a specific notification.

• ConvertNotificationToRequestPayload: An optional method allowing customization of the notification payload before sending it to webhooks.

Creating a Custom Webhook Event

To create a custom webhook event, follow these steps:

1. Derive from WebhookEventBase<TNotification>:

2. Override the Alias Property:

   Provide a unique identifier for your event using the Alias property:

3. Apply WebhookEventAttribute (Optional):

   You can use the WebhookEventAttribute to specify the event name and type. Apply this attribute to your custom event class:

   Umbraco already has some types as constants, which you can find at Constants.WebhookEvents.Types. If you do not specify this attribute, the event name will default to your alias, and the type will default to Other.

4. Implement Notification Handling:

   If needed, customize the handling of the notification in the HandleAsync method.

5. Register Your Webhook Event:

   Ensure that Umbraco is aware of your custom event by registering it in a composer:

6. Implement Optional Overrides: Depending on your requirements, you can override methods such as ConvertNotificationToRequestPayload and ShouldFireWebhookForNotification to customize the behavior of your webhook event.

Example Implementation

Here's a basic example of a custom webhook event:

Creating an event with the WebhookEventContentBase<TNotification, TEntity>

For scenarios where your webhook event is content-specific, Umbraco provides another base class: WebhookEventContentBase<TNotification, TEntity>. This class is an extension of the generic WebhookEventBase<TNotification> and introduces content-related functionalities.

The WebhookEventContentBase<TNotification, TEntity> class is designed for content-specific webhook events, where TEntity is expected to be a type that implements the IContentBase interface.

Usage

To leverage the WebhookEventContentBase<TNotification, TEntity> class, follow these steps:

1. Derive from WebhookEventContentBase<TNotification, TEntity>:
2. Override the Required Methods:

   • GetEntitiesFromNotification: Implement this method to extract content entities from the notification.

   • ConvertEntityToRequestPayload: Implement this method to customize the content entity payload before sending it to webhooks.

   If we take a look at the ContentPublishedWebhookEvent, we can see how these methods are overriden.
3. ProcessWebhooks Implementation:

   The ProcessWebhooks method in this class has been enhanced to iterate through content entities obtained from the notification. It checks the content type of each entity against the specified webhook's content type keys, firing webhooks only for matching entities.