Catalog My learning Blog
Full-Stack Developer Course: React, .NET and SQL Server · Phase 12 · Lesson 120 · 7 min read

Long-Running Operations and Outbound Webhooks in .NET

On this page
  1. Learning Objective
  2. Concept Explanation
  3. Worked Example: A Job API, Signed Deliveries and an SSRF-Safe HTTP Client
  4. Real-World Examples
  5. Review Questions & Answers

Learning Objective

Design an API for work that takes longer than a request should, using 202 Accepted and a status resource, deliver signed outbound webhooks with retries and replay protection, and prevent server-side request forgery when customers register their own callback URLs.

Concept Explanation

Some operations cannot finish inside a request: generating a large report, importing a file, running a bulk change, or transcoding media. Holding the HTTP connection open ties up resources, breaks when a proxy times out, and gives the user nothing while they wait. The standard REST design returns 202 Accepted immediately with a Location header pointing to a status resource, and does the work in a background worker, using the queue and outbox techniques of Days 65 and 66. The status resource reports a state such as queued, running, succeeded, failed, or cancelled, with progress and, on success, a link to the result. The client polls it, using a Retry-After hint to avoid hammering the server, or receives a push through SignalR from Day 59. Support cancellation with a DELETE or a cancel endpoint, make the job idempotent with an idempotency key so a retried request does not start a second job, and expire results and files after a defined time.

Authorization for jobs deserves care. The status URL must check that the caller owns the job, since job identifiers in a predictable sequence are an easy target for guessing, the same broken object level authorization risk as Day 50. Use unguessable identifiers, and when a job produces a file, hand out a short-lived signed link scoped to that user, not a public URL.

Outbound webhooks are the other direction: your system notifies your customers' systems by sending an HTTP request when something happens. They are widely used, and doing them well has several requirements. Sign each delivery so the receiver can verify it came from you, typically with an HMAC using a secret shared per endpoint, and include a timestamp in the signed content so a captured request cannot be replayed later. The Standard Webhooks specification describes a set of headers for this. Deliver at least once, with retries and exponential backoff for failures, a dead-letter store after the last attempt, and a delivery log the customer can inspect and replay. Tell receivers that they may see the same event twice, so events need a unique id for deduplication. Prefer thin payloads that carry an event type and identifiers and let the receiver fetch details with an authenticated call, so sensitive data is not pushed to arbitrary URLs. Use short timeouts, since a slow customer endpoint must never block your workers, and allow secret rotation with two valid secrets during a transition.

Letting customers register callback URLs creates a serious risk, server-side request forgery. If your server will fetch any URL a user provides, an attacker can point it at internal addresses, such as a cloud metadata service or an internal admin interface, and read the response through delivery logs or errors. Defend in layers: require HTTPS, resolve the host and reject private, loopback, and link-local addresses, connect to the address you validated so DNS cannot change between the check and the request, do not follow redirects, restrict ports, send from a network position with no route to sensitive internal systems, and never return the response body to the customer. On cloud platforms, require the hardened metadata service options and do not give the delivery worker broad permissions.

ConcernDesign
Work longer than a request202 Accepted, Location header, status resource
Progress and completionPolling with Retry-After, or push over SignalR
Duplicate submissionsIdempotency key per job creation
Job accessUnguessable ids, owner check, short-lived signed result links
Webhook authenticityHMAC signature over timestamp and body, secret per endpoint
Webhook deliveryAt-least-once, backoff, dead-letter, delivery log and replay
Registered URLsHTTPS only, block internal addresses, no redirects, pinned connection

Worked Example: A Job API, Signed Deliveries and an SSRF-Safe HTTP Client

The first block starts and reports a job. The following ones sign and deliver a webhook and block internal destinations.

C#
// Start: return 202 with a status location instead of holding the request open.
app.MapPost("/api/reports", async (CreateReportRequest req, AppDb db, ClaimsPrincipal user,
                                   [FromHeader(Name = "Idempotency-Key")] string? key, CancellationToken ct) =>
{
    if (string.IsNullOrWhiteSpace(key)) return Results.Problem("Idempotency-Key header is required.", statusCode: 400);
    var userId = user.GetUserId();

    var existing = await db.Jobs.SingleOrDefaultAsync(j => j.OwnerId == userId && j.IdempotencyKey == key, ct);
    if (existing is not null) return Results.Accepted($"/api/jobs/{existing.PublicId}");     // a retry returns the same job

    var job = new Job { PublicId = Guid.NewGuid(), OwnerId = userId, IdempotencyKey = key, State = JobState.Queued, Kind = "report" };
    db.Jobs.Add(job);
    db.Outbox.Add(OutboxMessage.From(new RunReport(job.PublicId, req)));                      // same transaction as the job row
    await db.SaveChangesAsync(ct);
    return Results.Accepted($"/api/jobs/{job.PublicId}");
}).RequireAuthorization();

app.MapGet("/api/jobs/{id:guid}", async (Guid id, AppDb db, ClaimsPrincipal user, HttpContext ctx, CancellationToken ct) =>
{
    var job = await db.Jobs.AsNoTracking().SingleOrDefaultAsync(j => j.PublicId == id && j.OwnerId == user.GetUserId(), ct);
    if (job is null) return Results.NotFound();                                              // not found for other people's jobs too
    if (job.State is JobState.Queued or JobState.Running) ctx.Response.Headers.RetryAfter = "3";
    return Results.Ok(new JobStatus(job.PublicId, job.State.ToString(), job.ProgressPercent, job.ResultUrl));
}).RequireAuthorization();
C#
// Signing: HMAC-SHA256 over "id.timestamp.body" in the style of the Standard Webhooks specification.
public static class WebhookSigner
{
    public static IDictionary<string, string> Sign(string eventId, string body, byte[] secret, DateTimeOffset now)
    {
        var ts = now.ToUnixTimeSeconds().ToString();
        using var hmac = new HMACSHA256(secret);
        var sig = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes($"{eventId}.{ts}.{body}")));
        return new Dictionary<string, string> { ["webhook-id"] = eventId, ["webhook-timestamp"] = ts, ["webhook-signature"] = $"v1,{sig}" };
    }
}
// Receiver side (documented for customers): recompute the HMAC over the raw body, compare in constant time,
// reject timestamps older than about five minutes, and deduplicate by webhook-id.
C#
// SSRF defense: an HTTP client that only connects to public addresses and never follows redirects.
public static HttpClient CreateWebhookClient() => new(new SocketsHttpHandler
{
    AllowAutoRedirect = false,
    ConnectTimeout = TimeSpan.FromSeconds(3),
    ConnectCallback = async (ctx, ct) =>
    {
        var addresses = await Dns.GetHostAddressesAsync(ctx.DnsEndPoint.Host, ct);
        var safe = addresses.FirstOrDefault(a => !IsPrivateOrReserved(a))
                   ?? throw new HttpRequestException("Destination address is not allowed.");
        var socket = new Socket(SocketType.Stream, ProtocolType.Tcp) { NoDelay = true };
        await socket.ConnectAsync(new IPEndPoint(safe, ctx.DnsEndPoint.Port), ct);          // connect to the address we validated
        return new NetworkStream(socket, ownsSocket: true);
    },
}) { Timeout = TimeSpan.FromSeconds(8) };

static bool IsPrivateOrReserved(IPAddress ip) =>
    IPAddress.IsLoopback(ip) || ip.IsIPv6LinkLocal || ip.IsIPv6SiteLocal ||
    (ip.AddressFamily == AddressFamily.InterNetwork && ip.GetAddressBytes() is var b &&
     (b[0] == 10 || b[0] == 127 || (b[0] == 172 && b[1] is >= 16 and <= 31) || (b[0] == 192 && b[1] == 168) ||
      (b[0] == 169 && b[1] == 254) || b[0] == 0));                                       // includes the cloud metadata address 169.254.169.254

// Registration also requires https and a bounded URL length; deliveries retry with backoff: 30s, 2m, 10m, 1h, 6h, then dead-letter.

Delivery workers also record the response status and a truncated response snippet for the customer's delivery log, but never the full body of a response from an address the customer controls, since it can contain anything.

A POST returns 202 Accepted with a Location header while a background worker runs the job, and the status resource is owner-only with an unguessable id. Outbound webhooks are signed with an HMAC over a timestamp and body, sent from an SSRF-safe client, and retried with backoff and a dead-letter store.
A POST returns 202 Accepted with a Location header while a background worker runs the job, and the status resource is owner-only with an unguessable id. Outbound webhooks are signed with an HMAC over a timestamp and body, sent from an SSRF-safe client, and retried with backoff and a dead-letter store.

Real-World Examples

  • In the 2019 Capital One breach, an attacker exploited a server-side request forgery flaw in a web application firewall to make the server request the cloud metadata service, obtained temporary credentials, and used them to read data on roughly 100 million customers. It is the canonical example of why outbound requests to user-supplied addresses need destination controls and least-privilege credentials.
  • Stripe signs its webhook events with a timestamp and an HMAC in the Stripe-Signature header and its libraries reject events whose timestamps are outside a tolerance, five minutes by default. The pattern, together with retries over several days and an event log with replay, has become the model that the Standard Webhooks specification generalizes.
Key TakeawaysReturn 202 Accepted with a status resource for long work, make job creation idempotent, authorize status and result access to the owner, and expire results. For outbound webhooks, sign with an HMAC over a timestamp and body, deliver at least once with backoff and a delivery log, prefer thin payloads, and defend against SSRF by validating destinations, pinning the connection, refusing redirects, and limiting network reach.

Review Questions & Answers

It frees the connection immediately, survives proxy timeouts, and lets the client check progress, cancel, or resume later. The work runs in a background worker and its result is reported through a resource that the client can poll or receive by push.

The receiver can reject requests whose timestamps are too old, so an attacker who captured a valid signed request cannot replay it later. The timestamp is part of the signed content, so it cannot be changed without invalidating the signature.

It is an attack that makes your server send requests to a destination the attacker chooses, including internal services and cloud metadata endpoints. A webhook URL is such a destination, so it must be validated, resolved to public addresses only, connected to without redirects, and sent from a restricted network.

Delivery is at least once, so a timeout or network failure can lead to a retry even when the first attempt was processed. Events carry unique ids, and receivers deduplicate on them so processing the same event twice has no effect.