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, WebhookInboundServiceTrigger, and a real Eltheon WebhookService.

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.
• WebhookService runs as an Eltheon service, 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 through feature-local file repositories by default, following the same persistence-first idea used by the Email service pattern.
• The default Webhooks storage root is GlobalConfig.Instance.Path/Webhooks; when GlobalConfig is not initialized yet, the fallback is ./DataAssets/Webhooks. Docker deployments must mount the configured DataAssets root persistently.
• IWebhookAdminQueryService exposes endpoints, subscriptions, queue state, and recent attempts for admin or diagnostics surfaces.
• Because delivery now runs through BaseService, the service can be started/stopped/triggered from the Eltheon admin service area and participates in trigger logging like the existing EmailService.

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>. Successful requests publish a safe in-process signal for WebhookInboundServiceTrigger; the trigger does not freely execute arbitrary services and only fires according to service trigger configuration.

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 to the filesystem by default.
• IWebhookAttemptRepository persists outbound attempt history to the filesystem by default 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.

Service Integration

• The package no longer relies on a standalone generic hosted worker.
• Delivery is handled by WebhookService, an Eltheon service derived from BaseService.
• This means the webhook dispatcher can use the existing service administration UI for:
  • start/stop
  • manual trigger execution
  • trigger configuration
  • service 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.