FluentCMS.Plugins.Webhooks
1.0.0-preview.1
dotnet add package FluentCMS.Plugins.Webhooks --version 1.0.0-preview.1
NuGet\Install-Package FluentCMS.Plugins.Webhooks -Version 1.0.0-preview.1
<PackageReference Include="FluentCMS.Plugins.Webhooks" Version="1.0.0-preview.1" />
<PackageVersion Include="FluentCMS.Plugins.Webhooks" Version="1.0.0-preview.1" />
<PackageReference Include="FluentCMS.Plugins.Webhooks" />
paket add FluentCMS.Plugins.Webhooks --version 1.0.0-preview.1
#r "nuget: FluentCMS.Plugins.Webhooks, 1.0.0-preview.1"
#:package FluentCMS.Plugins.Webhooks@1.0.0-preview.1
#addin nuget:?package=FluentCMS.Plugins.Webhooks&version=1.0.0-preview.1&prerelease
#tool nuget:?package=FluentCMS.Plugins.Webhooks&version=1.0.0-preview.1&prerelease
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 onev1for each secret that signs: one, or two while a rotated secret overlaps, the new one first.
A receiver:
- recomputes HMAC-SHA256 with its secret over
t + "." + body, the body as received, before parsing it; - compares the result with every
v1in constant time, and accepts the delivery when any of them matches; - refuses a
tmore than five minutes from its own clock, so a captured delivery cannot be replayed later; - answers 2xx quickly, and ignores a delivery whose
X-FluentCMS-Deliveryit 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 | Versions 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. |
-
net10.0
- FluentCMS.Plugins.Abstractions (>= 1.0.0-preview.1)
- FluentCMS.Sdk (>= 1.0.0-preview.1)
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 |