Redeon.SuperSiteEngineCore.Web.Eltheon.Core.Features.Webhooks

Webhook bridge, inbound route, and delivery infrastructure for Eltheon v3. This feature consumes internal Events, moves external webhook delivery onto an InMemory work queue, exposes Admin API/RCL surfaces, and keeps delivery attempts diagnosable through persisted history and admin-facing query models.

Scope: follow-up feature on top of Redeon.SuperSiteEngineCore.Web.Eltheon.Core.Features.Events and Redeon.SuperSiteEngineCore.Web.Eltheon.Core.Features.InMemory.

Install

dotnet add package Redeon.SuperSiteEngineCore.Web.Eltheon.Core.Features.Webhooks

DI Setup

builder.Services.AddEltheonEvents();
builder.Services.AddEltheonInMemory();

builder.Services.AddEltheonWebhooks(options =>
{
    options.QueueName = "eltheon.webhooks.dispatch";
    options.MaxAttempts = 3;
    options.RequestTimeout = TimeSpan.FromSeconds(10);
});

AddEltheonWebhooks(...) registers the publication registry, endpoint/subscription/inbound repositories, persisted attempt history, HMAC signing, outbound URL validation, inbound HMAC/Bearer/Query token validation, delivery services, an event bridge, typed permissions, navigation, an admin query service, and the supervised webhooks.dispatcher worker.

For packaged Admin/API discovery, register the RCL application part:

builder.Services
    .AddRazorPages()
    .AddEltheonWebhooksApplicationPart();

Register Publications

public sealed record UserCreatedEvent(string UserId, string Email) : IEvent
{
    public string EventName => "User.Created";
    public DateTime OccurredAtUtc { get; } = DateTime.UtcNow;
    public string? Source => "Identity";
    public string? CorrelationId => null;
    public string? Category => "Users";
}

public sealed class UserCreatedWebhookPublication
    : WebhookPublicationDefinition<UserCreatedEvent>
{
    public override string EventKey => "user.created";
    public override string Version => "v1";

    protected override object MapPayloadCore(UserCreatedEvent @event)
        => new { @event.UserId, @event.Email };

    protected override WebhookScope? ResolveScopeCore(UserCreatedEvent @event)
        => new()
        {
            ScopeType = WebhookScopeType.Scoped,
            ScopeKey = "tenant-42"
        };
}

builder.Services.AddSingleton<IWebhookPublicationDefinition, UserCreatedWebhookPublication>();

Delivery Model

• The bridge consumes internal IEvent instances via IEventProvider.
• Registered publication definitions translate internal events into webhook envelopes and can attach generic scope metadata.
• A WebhookDispatchItem is enqueued into the configured InMemory queue.
• WebhookDispatchWorker runs as the supervised webhooks.dispatcher workload, dequeues jobs, resolves subscriptions/endpoints, signs requests, and delivers them through HttpClient.
• Retryable delivery failures are re-enqueued until MaxAttempts is reached.
• Endpoints, subscriptions, inbound routes, and attempt history are persisted in the private webhooks Storage space when Eltheon Storage is available.
• Each missing Storage object may be read from the legacy Webhooks root during migration. Writes remain Storage-only and never recreate or mirror the legacy directory. Standalone hosts without Storage retain the configurable filesystem persistence.
• IWebhookAdminQueryService exposes endpoints, subscriptions, queue state, and recent attempts for admin or diagnostics surfaces.
• Worker lifecycle and diagnostics are owned by the Workload runtime; the feature has no direct dependency on the concrete Service package.

Canonical Events

AddEltheonWebhooks(...) registers Webhooks event metadata and emits canonical lifecycle events when events are enabled:

• Eltheon.Webhooks.EndpointCreated
• Eltheon.Webhooks.EndpointUpdated
• Eltheon.Webhooks.SubscriptionCreated
• Eltheon.Webhooks.SubscriptionUpdated
• Eltheon.Webhooks.DeliveryQueued
• Eltheon.Webhooks.DeliverySucceeded
• Eltheon.Webhooks.DeliveryFailed
• Eltheon.Webhooks.DeliveryBlocked
• Eltheon.Webhooks.InboundAccepted
• Eltheon.Webhooks.InboundRejected

Events default to enabled and can be disabled with WebhookEventOptions.EnableEvents = false. Payloads include stable ids, event keys, host/scheme, status, scope, attempt data, status code, and failure type. Endpoint secrets, HMAC signatures, full endpoint URIs, and outbound webhook payloads are not included.

Endpoint/subscription delete events are deferred because the current repository contracts expose only upsert/read operations.

Admin API And RCL

The feature contributes Admin pages under /Admin/Webhooks plus API endpoints under /api/v1/admin/webhooks. Protected pages and APIs use typed Webhooks permissions; navigation filtering is not treated as security. Mutating Admin APIs require anti-forgery validation.

German and English page resources include SimpleSearch metadata keys for the dashboard, endpoints, subscriptions, attempts, and inbound route pages.

Inbound Webhooks

Inbound requests are accepted under /api/v1/webhooks/inbound/{routeKey}. A route must be enabled and configured with one of the supported authentication modes: HMAC SHA-256, bearer token, or query token. HMAC requests must include timestamp and signature headers; bearer requests use Authorization: Bearer <token>; query-token requests use ?token=<token>. Accepted and rejected requests publish WebhookInboundLifecycleEvent; its IEventTriggerContext exposes only the route key and bounded outcome metadata to event trigger bindings.

Admin-created inbound routes generate a strong token when no secret is supplied. Generated or rotated values are returned once in the Admin API response and are redacted from later snapshots, lists, diagnostics, logs, events, and metrics.

Inbound diagnostics store route key, accepted/rejected state, remote address, payload byte count, and outcome. Raw payloads, HMAC signatures, and secrets are not stored in Admin responses.

Request Shape

Outbound requests use application/json and send a default envelope:

{
  "eventKey": "user.created",
  "version": "v1",
  "deliveryId": "8e85f8ee-fb73-45d8-baae-7d59152796f7",
  "eventId": "52a3c4c1-a6d0-4767-884e-b4af6b2dc58c",
  "occurredAtUtc": "2026-04-23T18:22:00Z",
  "timestampUtc": "2026-04-23T18:22:01Z",
  "source": "Identity",
  "correlationId": "request-42",
  "scope": {
    "scopeType": "Scoped",
    "scopeKey": "tenant-42"
  },
  "payload": {
    "userId": "123",
    "email": "hello@example.com"
  }
}

Headers include delivery id, event key, version, timestamp and, when an endpoint secret is configured, an HMAC signature.

Diagnostics And Admin Preparation

• IWebhookEndpointRepository, IWebhookSubscriptionRepository, and IWebhookInboundRouteRepository persist webhook configuration through Storage-first repositories.
• IWebhookAttemptRepository persists outbound attempt history in the webhooks space and keeps recent entries queryable.
• IWebhookAdminQueryService returns a diagnostics snapshot with:
  • registered endpoints
  • active subscriptions
  • current queue items
  • recent delivery attempts
• Scope is modeled in the webhook domain (WebhookScope) rather than in queue topology, so later products can map their own semantics on top.
• Endpoint secrets are optional. If a secret is configured the request is signed; if not, the webhook is sent without the signature header, which supports providers such as Discord.

Workload Integration

• Delivery is handled by WebhookDispatchWorker through the shared Workload runtime.
• The Workloads admin surface provides:
  • start/stop
  • supervised restart policy
  • runtime diagnostics
  • worker lifecycle logging

Tests

Redeon.SuperSiteEngineCore.Web.Eltheon.Core.Features.Webhooks.Test covers bridge mapping including scope propagation, signing and headers, dispatcher retry behavior, attempt history, diagnostics snapshots, service registration, DI registration, and lifecycle event payload safety.

Adviser contributor

AddEltheonWebhooks(...) contributes eltheon.webhooks.subscription-integrity. The read-only check validates endpoint existence and activation, scope compatibility, and the existing outbound URL policy. Subjects use stable prefixed GUID references; evidence does not contain endpoint URLs, hosts, names, secrets, event keys, or scope keys. The Webhooks package references only Core.Abstractions and does not depend on the concrete Adviser feature.