FluentCMS.Plugins.Webhooks 1.0.0-preview.1

This is a prerelease version of FluentCMS.Plugins.Webhooks.
dotnet add package FluentCMS.Plugins.Webhooks --version 1.0.0-preview.1
                    
NuGet\Install-Package FluentCMS.Plugins.Webhooks -Version 1.0.0-preview.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="FluentCMS.Plugins.Webhooks" Version="1.0.0-preview.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="FluentCMS.Plugins.Webhooks" Version="1.0.0-preview.1" />
                    
Directory.Packages.props
<PackageReference Include="FluentCMS.Plugins.Webhooks" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add FluentCMS.Plugins.Webhooks --version 1.0.0-preview.1
                    
#r "nuget: FluentCMS.Plugins.Webhooks, 1.0.0-preview.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package FluentCMS.Plugins.Webhooks@1.0.0-preview.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=FluentCMS.Plugins.Webhooks&version=1.0.0-preview.1&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=FluentCMS.Plugins.Webhooks&version=1.0.0-preview.1&prerelease
                    
Install as a Cake Tool

FluentCMS.Plugins.Webhooks

Signed deliveries of content and cache events to the webhooks of a site, with retries and a delivery log. The webhooks are managed under /api/management/v1/webhooks with the permission webhooks.manage. Section 5.2 of the backend technical specification has the full design.

Settings

The options are in FluentCms:Webhooks:

Key Default Meaning
AllowPrivateNetworks false Lets deliveries reach loopback, private, link-local and the other addresses that are not public. Turn it on only when every receiver is internal.
Timeout 00:00:10 How long an attempt waits for the receiver's answer, at most five minutes.
Retention 30.00:00:00 How long the delivery log keeps an attempt.
Workers 2 Workers of the webhooks job queue on this instance. 0 runs no deliveries here.
SecretOverlap 1.00:00:00 How long the secret a rotation replaces keeps signing beside the new one. 00:00:00 ends it at the rotation.
DisableAfter unset Disables a webhook when a delivery to it dies and every attempt to it has failed for at least this long. Unset never disables one. At most Retention.

The webhooks queue

Every attempt runs on the job queue webhooks: the first attempt of a delivery, its retries at 1m, 5m, 30m, 2h and 24h, a redelivery and a ping. A receiver that hangs holds the workers of this queue for its timeout, and scheduled publishing and the other jobs of the default queue keep running. FluentCms:Jobs:Queues:webhooks sets the workers too, and wins over Workers.

One attempt of a webhook is in flight at a time, on every instance together. A job claims its attempt by writing the attempt's row as pending before it sends, and a job that finds another attempt of its webhook pending waits until that attempt's send must have ended, at least a few seconds, and tries again. So a slow receiver delays its own deliveries and nobody else's.

A claim that is still pending a minute after the timeout has passed is abandoned, because its worker stopped before it recorded the result. The next job to find it marks the attempt failed and schedules the next attempt, without sending this one again. Since the receiver may have got the abandoned attempt, it can get a delivery more than once, and ignores a repeat by its X-FluentCMS-Delivery header.

Dead deliveries

A delivery whose sixth attempt fails is dead, and its activity row is webhook.delivery_dead, with the delivery id, the event and the number of attempts. A ping or a redelivery is tried once and makes no such row. The webhook stays enabled unless DisableAfter is set: then, when a delivery dies and every attempt to the webhook has failed for at least that long, the webhook is disabled, with the activity row webhook.disabled and the time it started failing. A ping that succeeds counts as a success, and so does a change of the webhook: the time starts again from it. Turn the webhook back on with a PUT once the receiver works.

Secrets and headers

The secret is the caller's, or generated and returned by that create call only. The values of a webhook's headers are secrets too, since a receiver's credentials, such as Authorization, are what they are for. Both are stored protected with Data Protection. No answer holds a header's value, the one to a create included: each header is listed by name with the value ***. Sending *** back in a PUT keeps the value stored under that name, so a webhook read and sent back keeps its headers. Deliveries send the real values.

Webhooks saved before the headers were protected hold them in plain JSON. They are still delivered, and the plugin protects them once the host has started, or when the webhook is next saved.

PUT with a new secret rotates it. For SecretOverlap, 24 hours by default, the secret it replaces still signs every delivery beside the new one, and the answers carry previousSecretExpiresAt. Then only the new secret signs. Change the receiver over to the new secret within that time.

The body

{ version, id, event, occurredAt, site, origin, actor, data, links }, where version is 1. It changes only with a change that a receiver of version 1 could misread, and a new field is not one. A redelivery sends the body exactly as it was first sent.

The body names the entry and carries none of its fields. A receiver that needs the entry fetches it when the delivery arrives: it reads data.type, data.documentId and data.locale, and gets the entry from links.delivery with a Delivery key and locale, or from links.management with a Management key for a draft. It then has the entry as its own key sees it and as it is now, even for a retry that arrives hours later, and data.version tells it whether what it read is older or newer than the event.

Receivers

A target URL uses https outside Development. Deliveries do not follow redirects and do not go through a system proxy. Every delivery carries:

  • X-FluentCMS-Event, the event's name;
  • X-FluentCMS-Delivery, the delivery id, the same for every attempt of a delivery;
  • X-FluentCMS-Signature: t=<unix>,v1=<hex>, with one v1 for each secret that signs: one, or two while a rotated secret overlaps, the new one first.

A receiver:

  1. recomputes HMAC-SHA256 with its secret over t + "." + body, the body as received, before parsing it;
  2. compares the result with every v1 in constant time, and accepts the delivery when any of them matches;
  3. refuses a t more than five minutes from its own clock, so a captured delivery cannot be replayed later;
  4. answers 2xx quickly, and ignores a delivery whose X-FluentCMS-Delivery it has already handled, since a retry or an attempt whose result was lost sends it again.

In C#:

static bool Verifies(string signature, string secret, string body, DateTimeOffset now)
{
    var parts = signature.Split(',').Select(part => part.Split('=', 2)).Where(part => part.Length == 2).ToList();
    if (parts.FirstOrDefault(part => part[0] == "t")?[1] is not { } t
        || !long.TryParse(t, NumberStyles.None, CultureInfo.InvariantCulture, out var seconds)
        || Math.Abs(now.ToUnixTimeSeconds() - seconds) > 300)
    {
        return false;
    }

    var mac = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), Encoding.UTF8.GetBytes(t + "." + body));
    var expected = Encoding.ASCII.GetBytes(Convert.ToHexStringLower(mac));
    return parts.Where(part => part[0] == "v1").Any(part => CryptographicOperations.FixedTimeEquals(expected, Encoding.ASCII.GetBytes(part[1])));
}
Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.0-preview.1 50 11/16/2026