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.

Repository and package moves change the project scope used for delivery, diagnostics, and manual redelivery. Disable affected source-project webhooks before moving, wait for admitted outgoing attempts to finish, and explicitly review destination endpoints. Reenabling an old endpoint does not restore access to moved events. Event envelopes keep their original project evidence; historical pipeline events keep the run's execution project. A retained event identifier or payload project is not current delivery authority.

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.

Call scoped APIs with a session-bound human token.

Create a personal access token in the target tenant workspace under Settings › Access › API tokens. The token is bound to that one organization and its human owner. Choose only Manage projects when the integration must list or create projects, and only Manage work when it must manage project work. Choose Provision source to list, create, or import repositories and list or register named pipeline definitions. This scope does not issue Git credentials, execute pipelines, delete configuration, or publish packages.

Issue PATs from a personal-account organization session with fresh local MFA. Company/provider-only sessions cannot issue PATs. Select Issue API token to review the exact organization, expiry and requested scopes. Confirming that review opens the required MFA prompt automatically; complete the passkey or authenticator challenge to continue issuance. Cancelling the review or challenge does not issue a token. Each scope shows its claim name separately from its description.

A PAT retains human purpose and its exact issuing tenant session. Every request must satisfy the current action policy and session evidence; logout, session rotation or loss of required proof can stop access before token expiry. A PAT never receives a machine-policy exception. Repository or package credentials delegated through it retain human provenance and their own scopes, expiry and revocation controls. Previously issued PATs without session evidence cannot satisfy actions that require that evidence. Use an explicitly supported machine-purpose credential for unattended Git or package access where the organization policy permits it.

Integrations can link to the target organization workspace at /settings/access/api-tokens?organization=<organization-uuid>&scopes=manage_source,run_pipelines,manage_packages&name=Migration&expires_in_days=1. Use the workspace's own tenant origin and immutable organization ID. The link preselects a request for the user to inspect and approve; it never issues a token automatically. Only the four shown query parameters are accepted. Requested scopes must be supported, and the organization must match the workspace. Duplicate parameters, callbacks, redirect destinations and token parameters are rejected. Never put credentials or confidential data in the URL. The issued token appears only once after approval and must be transferred through a protected channel.

1. Keep the target explicit.Use the matching tenant hostname and verify the organization ID before any mutation. A token for one organization is never accepted for another.
2. Send the bearer in one header.Use Authorization: Bearer <token>. Do not place the value in a URL, source file, payload, work item, log, status file, or command transcript.
3. Use protocol controls.Supply Idempotency-Key where the endpoint supports it, and use the current ETag with If-Match for version-checked assignment or relation changes.
4. Reconcile uncertainty.If a non-idempotent Work mutation loses its response, read current server state before deciding whether to repeat it. Never infer that a timeout means the mutation did not commit.
5. Close one-off access.Verify counts and relationships, then revoke the token with fresh MFA. Expiry, revocation, issuing-session logout or rotation, membership removal, action-policy changes and live role changes take effect without waiting for the token lifetime.

Resolve common integration failures.