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 before deserializing it, then treat the provider event id as an inbox key. The inbox row and outbox command commit together so acknowledgement never outruns durable acceptance.

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();

    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",
        new { envelope.EventId, Body = body }));
    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(); // A concurrent delivery already persisted this event.
    }
    return Results.Accepted();
});

The endpoint performs only delivery authentication and durable intake. A unique index on (Provider, EventId) is still required for concurrent duplicates; signature secrets need rotation support without accepting arbitrary old keys forever.

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