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

Webhook bridge and delivery infrastructure for Eltheon v2. This feature consumes internal Events, moves external webhook delivery onto an InMemory work queue, 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, in-memory endpoint/subscription repositories, persisted attempt history, HMAC signing, delivery services, an event bridge, an admin query service, and a real Eltheon WebhookService.

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.
• Attempt history is persisted through IWebhookAttemptRepository, following the same persistence-first idea used by the Email service pattern.
• 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

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.

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

• IWebhookAttemptRepository persists 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.