Add support for customizable Webhook Payload Providers

[erikjanwestendorp]

Currently the webhook system allows you to configure webhooks for specific events and add headers. However, for many integrations you may need to customise what is sent in the webhook payload (for example, selecting specific properties, formatting differently, injecting additional metadata, etc).

I’ve been playing with the idea of making this possible using Webhook Payload Providers. These providers should make it possible to override the default webhook payload. I’ve just created a draft PR to demonstrate how it works. I’m curious to hear if this is something that could be added?

Of course, there are a few things to take into account:

• This is probably a breaking change
• The implementation in the current PR requires some rework due to the dependency on WebhookPayloadProviderCollection.
• Retrieving the correct provider currently happens in multiple places (WebhookEventContentBase, WebhookEventBase), this could be done in a cleaner way.

An example of how this could work:

using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.Notifications;
using Umbraco.Cms.Core.Webhooks;

namespace Umbraco.Cms.Web.UI;

public class MyCustomWebhookPayloadProvider : WebhookPayloadProviderBase<ContentPublishedNotification>
{
    protected override bool CanHandle(Uri endpoint, string eventAlias, ContentPublishedNotification notification,
        IWebhook webhook)
    {
        var host = endpoint.Host.ToLowerInvariant();
        var isWebhookSite = host.Contains("webhook.site");
        return isWebhookSite;
    }

    protected override object BuildPayload(ContentPublishedNotification notification, Uri endpoint, string eventAlias,
        IWebhook webhook)
        => new {messgage = "Published new Content"};
}

[Migaroez]

Hey @erikjanwestendorp, thank you for reaching out.

The current way of changing a webhookevent's payload is to replace the webhookevent with a custom one. See: https://docs.umbraco.com/umbraco-cms/reference/webhooks#replacing-webhook-events. Your solution seems to shift the responsibility of building that payload to another class that is in a one on one relation with the webhookevent. If there is none present then it would run the payload creation logic on the webhookevent itself.
This in my opinion would not improve the developer experience, it would maybe even make it more convoluted.

Looking at the code and the implementation example you provided, it seems to me that you need the following two things:

• Make it easier to decide whether a specific webhook should be notified in webhookevents. This could be done by introducting something similar to what we do on notification level
  public virtual bool ShouldFireWebhookForNotification(TNotification notificationObject) => true; and consuming it in the webhook loop inside ProcessWebhooks
• Make it easier to customize the webhookpayload for a specific webhook in webhookevents. This can be done by passing the IWebhook (which holds the endpoint) into the ConvertEntityToRequestPayload and ConvertNotificationToRequestPayload methods.

Both of these should be able to be included in a non breaking way. Please let me know if this would cover your needs and I will take your updated proposal to the team.

[erikjanwestendorp]

Hi @Migaroez, I’m indeed aware that the entire webhook event can be replaced, and the solution I provided here isn’t ideal yet. Fully replacing the webhook event doesn’t completely solve the problem, since that would cause the payload to be modified in all cases. What I’d like is for it to only happen for certain URLs (for example, we use Teams webhooks which require a custom payload). However, I want the payload for other webhooks to remain unchanged.

Passing IWebhook to ConvertEntityToRequestPayload and ConvertNotificationToRequestPayload could indeed be useful. In that case, I could replace the webhook event and then check the webhook URL to decide whether or not to adjust the payload accordingly. But wouldn’t adding IWebhook be a breaking change, or am I mistaken?

Additionally, I think it would be convenient for developers to have some kind of interface for example, IWebhookPayloadProvider that allows specifying that if it’s this particular event and this specific webhook URL, then use a different payload instead of replacing the entire event.