Implement a payment webhook endpoint that responds quickly without processing the business event inline.

Validate provider timestamp and HMAC over the exact raw body. Persist each provider event id once, enqueue processing atomically, and acknowledge valid duplicates without reapplying them.

The provider retries the same signed event after a timeout; the endpoint returns success but creates no second payment transition.

• Read a bounded raw body.
• Compare signatures in constant time.
• Reject stale timestamps.
• Enforce a unique provider event id.

I authenticate the delivery over the exact bounded bytes before deserializing it, then treat the provider event id as an inbox key. After validation I build the smallest event envelope the asynchronous handler needs. The inbox row and that outbox command commit together, so acknowledgement never outruns durable acceptance and the default design does not copy an entire payment payload into long-lived storage.

app.MapPost("/webhooks/payments", async Task<IResult> (HttpRequest request,
    AppDbContext db, PaymentWebhookVerifier verifier, CancellationToken ct) =>
{
    var body = await request.ReadBoundedBodyAsync(maxBytes: 256_000, ct);
    if (!verifier.TryVerify(request.Headers, body, out var verifiedAt))
        return Results.Unauthorized();

    var age = TimeProvider.System.GetUtcNow() - verifiedAt;
    if (age < TimeSpan.FromMinutes(-1) || age > TimeSpan.FromMinutes(5))
        return Results.Unauthorized();

    PaymentEnvelope? envelope;
    try {
        envelope = JsonSerializer.Deserialize<PaymentEnvelope>(body);
    } catch (JsonException) {
        return Results.BadRequest();
    }
    if (envelope is null || string.IsNullOrWhiteSpace(envelope.EventId))
        return Results.BadRequest();

    var command = new PaymentWebhookReceived(
        envelope.EventId,
        envelope.EventType,
        envelope.TransactionId,
        envelope.OccurredAtUtc);

    await using var tx = await db.Database.BeginTransactionAsync(ct);
    var seen = await db.WebhookInbox.AnyAsync(
        x => x.Provider == "payments" && x.EventId == envelope.EventId, ct);
    if (seen) return Results.Ok();

    db.WebhookInbox.Add(new WebhookInbox("payments", envelope.EventId));
    db.OutboxMessages.Add(OutboxMessage.Create(
        "payment.webhook.received", command));
    try {
        await db.SaveChangesAsync(ct);
        await tx.CommitAsync(ct);
    } catch (DbUpdateException ex) when (
        UniqueConstraints.IsViolation(ex, "UX_WebhookInbox_Provider_EventId")) {
        await tx.RollbackAsync(ct);
        return Results.Ok();
    }

    return Results.Accepted();
});

The endpoint performs delivery authentication and durable intake only. A unique index on (Provider, EventId) handles concurrent duplicates, and signature-secret rotation must not accept arbitrary old keys forever. If audit or dispute handling truly requires the exact raw payload, store it encrypted behind narrow access with explicit retention and deletion; copying it into every outbox message is not the default.

• Two duplicates arrive together.
• The timestamp is in the future.
• The JSON is invalid after a valid signature.
• The provider rotates its secret.

• Sign the exact bytes and mutate one byte.
• Send stale and future timestamps.
• Dispatch concurrent duplicates.
• Assert no business handler runs inline.

• Re-serializing JSON before signature verification.
• Trusting only event id without HMAC.
• Acknowledging before durable storage.
• Running payment transitions in the request.
• Persisting the full raw payment payload by default when a validated minimal envelope is sufficient.