Webhooks

Umbraco webhooks enable seamless integration and real-time updates by notifying external services about content changes and events within the Umbraco CMS

Webhooks provide real-time, event-driven communication within Umbraco. They enable external services to react to content changes instantly by sending HTTP requests when specific events occur. This allows you to integrate with third-party services, automate workflows, and synchronize data effortlessly.

Getting Started

To manage webhooks, navigate to Settings > Webhooks in the Umbraco backoffice.

Webhooks section

To create a webhook, click Create. This opens the webhook creation screen where you can configure the necessary details.

Creating a webhook

Configuring a Webhook

URL

The Url is the endpoint where the webhook will send an HTTP request when the selected event is triggered. Ensure this endpoint is publicly accessible and capable of handling incoming requests.

Events

Webhooks are triggered by specific events in Umbraco. By default, the following events are available:

Event Name	Description
Content Published	Fires when content is published.
Content Unpublished	Fires when content is unpublished.
Content Deleted	Fires when content is deleted.
Media Deleted	Fires when a media item is deleted.
Media Saved	Fires when a media item is saved.

Content Type Filtering

For Content or Media events, you can specify whether the webhook should trigger for all content types or only specific ones. This is useful when you only need webhooks for certain document types, such as blog posts or products.

Custom Headers

You can define custom HTTP headers that will be included in the webhook request. Common use cases include:

• Specifying request format: Accept: application/json

• Adding authentication tokens: Authorization: Bearer <your-token>

• Including security headers

Default Behavior of Umbraco Webhooks

Umbraco webhooks come with predefined settings and behaviors.

JSON Payload

Each webhook event sends a JSON payload. For example, the Content Published event includes full content details:

{
  "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": {}
}

The Content Deleted event sends only the content ID:

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

Default Headers

Webhook requests include the following headers by default:

Header Name	Description
user-agent: Umbraco-Cms/{version}	Identifies the Umbraco version sending the webhook.
umb-webhook-retrycount: {number}	Indicates the retry count for a webhook request.
umb-webhook-event: {event}	Specifies the event that triggered the request. Example: umb-webhook-event: Umbraco.ContentPublished.

Extending Webhooks

Adding Custom Events

You can extend the list of webhook events using IUmbracoBuilder and IComposer. Here’s an example of how to add custom webhook events:

using Umbraco.Cms.Core.Composing;

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

To enable all available events, use:

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

Replacing Webhook Events

You can modify existing webhook events, such as changing the payload format, by creating a custom implementation:

[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
        {
            CustomData = "Your data",
            PublishedContent = publishedContent is null ? null : _apiContentBuilder.Build(publishedContent)
        };
    }
}

To replace the default Umbraco webhook with your custom implementation:

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

Webhook Settings

Webhook settings are configured in appsettings.*.json under Umbraco::CMS:

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

Setting	Description
Enabled	Enables or disables webhooks.
MaximumRetries	Sets the maximum number of retry attempts.
Period	Defines the retry interval.
EnableLoggingCleanup	Enables automatic cleanup of logs.
KeepLogsForDays	Determines how long webhook logs are retained.

Testing Webhooks

Use Beeceptor or RequestBin to test your event trigger integrations before deploying them to production.