Connect a project with signed webhooks.

Own both ends of the delivery.

The webhook is governed in the project whose events it exports; the project-scoped Manage projects claim controls this workflow.

Build the endpoint before creating the webhook.

1. Expose one HTTPS route.Use a dedicated path such as /hooks/mozaic with a certificate trusted by normal public HTTPS clients.
2. Read the raw body once.Signature verification covers the exact bytes sent. Do not parse, reformat, transcode, or reconstruct JSON before computing the HMAC.
3. Persist an idempotency key.Use event_id as a unique processing key. A manual redelivery creates a new delivery but carries the same event.
4. Acknowledge quickly.Verify, durably enqueue or record the event, and return a 2xx response. Perform slow integration work after acknowledgement.
5. Keep a safe diagnostic trail.Record the delivery ID, event ID, event type, result, and processing time without logging the signing secret or sensitive payload unnecessarily.

Create a project webhook.

1. Choose Endpoint.From an empty state the equivalent action is Create project endpoint. Enter a recognizable name, such as Release index or Deployment events.
2. Enter the destination.Use an HTTPS URL on a public DNS hostname. URLs containing credentials, fragments, IP literals, localhost, or private destinations are rejected.
3. Select events.Choose at least one exact event type from the supported list. Send only the data the receiver needs.
4. Create the endpoint.Mozaic returns a signing secret beginning with mwhsec_.
5. Copy the secret immediately.Store it in the receiver's secret manager. Mozaic derives the signing value when dispatching and does not expose it again.

Names are limited to 120 characters. Destination URLs are limited to 2,048 characters. Updating an endpoint changes future deliveries only; existing delivery records retain their original evidence.

Subscribe to exact, versioned event names.

Filters are an allowlist. A new product event is not sent to an existing endpoint unless its exact type is selected. Treat the envelope's schema_version and event_type as protocol values, and ignore additive JSON properties your version does not use.

Use headers for delivery context and JSON for domain data.

Request headers

Version-one event envelope

Identity

event_id, organization_id, placement_generation, event_type, and schema_version.

Subject and actor

resource, actor, and visibility preserve the organization-bound subject and originator.

Ordering and tracing

aggregate_sequence, correlation_id, optional causation_id, and occurred_at.

Event data

payload is an event-specific JSON object, bounded to 64 KiB.

Aggregate sequence helps order events for one resource; it is not a global ordering guarantee. Correlation and causation values connect related operations but do not replace receiver idempotency.

Authenticate the exact bytes before parsing.

The signing key is the complete show-once mwhsec_... string encoded as UTF-8. Compute HMAC-SHA-256 over the raw body, prefix the lowercase hex digest with sha256=, and compare in constant time.

using System.Globalization;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

app.MapPost("/hooks/mozaic", async (HttpRequest request, IConfiguration config) =>
{
    using var buffer = new MemoryStream();
    await request.Body.CopyToAsync(buffer);
    var body = buffer.ToArray();

    var secret = config["Mozaic:WebhookSecret"];
    var supplied = request.Headers["X-Mozaic-Signature-256"].ToString();
    var timestampText = request.Headers["X-Mozaic-Delivery-Timestamp"].ToString();
    if (string.IsNullOrEmpty(secret) ||
        !DateTimeOffset.TryParse(timestampText, CultureInfo.InvariantCulture,
            DateTimeStyles.AssumeUniversal, out var timestamp) ||
        Math.Abs((DateTimeOffset.UtcNow - timestamp).TotalMinutes) > 5)
    {
        return Results.Unauthorized();
    }

    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var expectedText = "sha256=" +
        Convert.ToHexString(hmac.ComputeHash(body)).ToLowerInvariant();
    var expected = Encoding.ASCII.GetBytes(expectedText);
    var actual = Encoding.ASCII.GetBytes(supplied);
    if (expected.Length != actual.Length ||
        !CryptographicOperations.FixedTimeEquals(expected, actual))
    {
        return Results.Unauthorized();
    }

    using var envelope = JsonDocument.Parse(body);
    var eventId = envelope.RootElement.GetProperty("event_id").GetGuid();
    // Insert eventId with a unique constraint and enqueue work atomically.
    return Results.NoContent();
});

1. Reject missing context.Require the signature, timestamp, delivery ID, and event header.
2. Bound replay.Parse the delivery timestamp and accept a small clock-skew window appropriate to your ingress. The example uses five minutes.
3. Compute the HMAC.Use the full secret and exact body bytes.
4. Compare in constant time.Reject different lengths and invalid digests before parsing or acting on the event.
5. Validate the envelope.Require schema version 1, a known event type, and an expected project or organization binding before dispatching application logic.

Make every handler idempotent.

1. Start a local transaction.Insert event_id into a receipt table with a unique constraint and enqueue or record the intended work in the same transaction.
2. Treat duplicates as success.If the event ID already exists, return 2xx without repeating the side effect. A manual redelivery is expected to reach this path.
3. Return before slow work.The entire HTTP attempt has a 15-second timeout. A durable queue or outbox lets your business action continue independently.
4. Handle each event version explicitly.Route on both event_type and schema_version; log and safely acknowledge or quarantine unsupported versions according to your policy.
5. Use resource sequence carefully.For state projections, retain the highest accepted aggregate_sequence per resource and reconcile gaps from Mozaic instead of assuming global delivery order.

Inspect the exact attempt before redelivering.

Pending

The delivery is recorded and waiting to be leased by the dispatcher.

In flight

One dispatcher owns the active HTTP attempt.

Succeeded

The receiver returned any 2xx status.

Failed

The dispatcher completed the attempt and received a non-2xx response or rejected the destination.

Unknown

The request or response did not complete with enough evidence to know whether the receiver acted, such as a transport failure or interrupted response read.

Mozaic makes one automatic attempt. It does not automatically retry Failed or Unknown deliveries. The record includes event type, kind, status, timing, HTTP status when known, a bounded error, and up to 4,096 bytes of response excerpt.

Manual redelivery

1. Open the terminal delivery.Inspect its status, response, receiver logs, and event ID.
2. Fix or confirm the receiver.For Unknown, first check whether the original event was already recorded.
3. Choose Redeliver.Fresh authentication and Manage projects are required.
4. Follow the new record.Mozaic creates a distinct Manual redelivery linked to the original; it never rewrites the Initial attempt.

Rotate without leaving stale trust behind.

Rotate a signing secret

1. Open the webhook settings.Confirm the endpoint identity and coordinate a short receiver change window.
2. Choose Rotate secret.Fresh authentication is required. Copy the new mwhsec_... value from the show-once response.
3. Update the receiver immediately.The previous secret becomes invalid as soon as rotation succeeds; there is no dual-secret overlap.
4. Verify the next delivery.Confirm the endpoint accepts the new signature and no secret appears in logs.

Deactivate an endpoint

Deactivate the webhook to stop future matching events from creating deliveries. Existing endpoint metadata and delivery history remain available as evidence. Reactivate only after the destination and secret configuration are ready again.

Design inside the outbound boundary.

• Treat the signing secret like a password. Store it in a secret manager and grant the receiver process read access only.
• Signature verification authenticates content; it does not make every event appropriate for every downstream action. Enforce your own resource and event allowlists.
• Return generic, bounded error bodies. Response excerpts are retained in Mozaic and should not contain credentials or sensitive internal diagnostics.
• Expect additive payload fields. Fail closed on unsupported schema versions, but avoid breaking on fields your handler does not consume.

Resolve common integration failures.