Why Webhooks Need Idempotency Keys (And How to Implement Them)

Without an idempotency key, that retry will re-run your payment confirmation, generate a duplicate order, create duplicate CRM contacts, or dispatch a second notification to the customer.

1. The Core Problem: The Illusion of "Failed" Requests

Every developer learns early that an HTTP 500 or timeout means a request failed. In webhook architectures, this assumption causes catastrophic bugs when consumers treat retries as new events.

Why Naive Database Lookups Fail (The Race Condition Trap)

A common developer impulse is to write a pre-check query like:

if (await _dbContext.Orders.AnyAsync(o => o.StripeEventId == eventId))
{
    return Ok(); // Already handled
}

This works during single-threaded manual testing. However, in production, providers often fire concurrent retries when their HTTP connection experiences socket resets. Both requests hit the database query before either one has committed its transaction. Both checks return false, and both threads proceed to insert duplicate records.

2. The Solution: Distributed Atomic Idempotency Filter

To ensure an operation is strictly idempotent (producing identical state regardless of whether it is invoked once or ten times), we decouple duplicate detection from our primary database using a fast, atomic memory store such as Redis.

3. Production ASP.NET Core Implementation

Here is a production-hardened action filter attribute in C# leveraging IDistributedCache:

using System.Security.Cryptography;
using System.Text;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;
using Microsoft.Extensions.Caching.Distributed;

namespace Celes7a.Web.Infrastructure.Filters;

[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
public class IdempotentWebhookAttribute : Attribute, IAsyncActionFilter
{
    private readonly string _headerName;
    private readonly int _ttlHours;

    public IdempotentWebhookAttribute(string headerName = "X-Webhook-Event-Id", int ttlHours = 24)
    {
        _headerName = headerName;
        _ttlHours = ttlHours;
    }

    public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
    {
        var cache = context.HttpContext.RequestServices.GetRequiredService<IDistributedCache>();
        var request = context.HttpContext.Request;

        // 1. Resolve Idempotency Identifier
        string idempotencyKey;
        if (request.Headers.TryGetValue(_headerName, out var headerValue) && !string.IsNullOrWhiteSpace(headerValue))
        {
            idempotencyKey = headerValue.ToString();
        }
        else
        {
            // Fallback: Hash raw request body
            request.EnableBuffering();
            using var reader = new StreamReader(request.Body, Encoding.UTF8, leaveOpen: true);
            var body = await reader.ReadToEndAsync();
            request.Body.Position = 0;
            idempotencyKey = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(body)));
        }

        var cacheKey = $"idempotency:webhook:{idempotencyKey}";

        // 2. Check Cache
        var existingStatus = await cache.GetStringAsync(cacheKey);
        if (existingStatus == "completed")
        {
            context.Result = new OkObjectResult(new { status = "duplicate_ignored", key = idempotencyKey });
            return;
        }

        if (existingStatus == "in-flight")
        {
            context.Result = new StatusCodeResult(StatusCodes.Status429TooManyRequests);
            return;
        }

        // 3. Mark in-flight with short safety TTL
        await cache.SetStringAsync(cacheKey, "in-flight", new DistributedCacheEntryOptions
        {
            AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(2)
        });

        // 4. Execute downstream business logic
        var executedContext = await next();

        // 5. Finalize state
        if (executedContext.Exception == null || executedContext.ExceptionHandled)
        {
            await cache.SetStringAsync(cacheKey, "completed", new DistributedCacheEntryOptions
            {
                AbsoluteExpirationRelativeToNow = TimeSpan.FromHours(_ttlHours)
            });
        }
        else
        {
            await cache.RemoveAsync(cacheKey);
        }
    }
}

4. Operational Hardening Checklist