DEV Community

Cover image for Webhook Timeouts: Provider Limits and the Acknowledge-First Pattern
mmiura for SHANNON LIMITED LIABILITY COMPANY

Posted on Originally published at webhookadmin.com

Webhook Timeouts: Provider Limits and the Acknowledge-First Pattern

Webhook timeouts run from 2 seconds at LINE to 60 at SmartHR. We put the documented limits in one table with sources and show the pattern that works against all of them: verify, store, return 2xx, and process later.

Webhook senders give you a fixed amount of time to respond, and it varies a lot: the limits providers document run from 2 seconds to 60 seconds. The one approach that works against all of them is to verify the signature, store the event, return 2xx immediately, and process it afterwards. This post lists the documented limits with sources, then shows that pattern in code, including the serverless cases where "process it afterwards" quietly doesn't happen.

Provider timeouts

Checked against each provider's official documentation on 2026-09-27. Where a provider doesn't state a number, the table says so.

Provider Response timeout What happens next
LINE (Messaging API) 2 s Redelivery is off by default; can be enabled
Slack (Events API) 3 s Up to 3 retries: almost immediately, after 1 min, after 5 min
Zoom 3 s Retries after 5, 20 and 60 min (5xx and certain network errors only)
Shopify 5 s Up to 8 retries over 4 hours; the subscription is removed if failures persist
GitHub 10 s No automatic redelivery (manual or via the API)
SmartHR 60 s Up to 17 attempts over about 3 days in production
Stripe Not stated ("return a 2xx quickly") Exponential backoff for up to 3 days in live mode

Sources (all checked 2026-09-27): LINE error statistics, LINE receiving messages, Slack Events API, Zoom webhooks, Shopify troubleshooting, GitHub best practices, GitHub failed deliveries, SmartHR, Stripe webhooks

A few details worth knowing:

  • LINE's 2-second limit appears in its error statistics docs, under the request_timeout category. The same page notes that your server may still have received the webhook even when it's counted as a timeout. In other words, the work may have happened, and if redelivery is on, the event arrives again.
  • Slack sends x-slack-retry-num and x-slack-retry-reason (for example http_timeout) on retries. Repeated slow responses can also get your event subscriptions turned off (Webhook response status codes has the conditions).
  • Stripe lists "(Timeout) ERR" among delivery errors and tells you to defer complex logic and return a success response immediately, but doesn't say how long it waits.

For comparison, Webhook Admin (as a sender) times out after 15 seconds and retries anything that isn't a 2xx (signature verification docs).

Why timeouts create duplicates

When you miss the deadline, the sender records a failure, even if your code went on to finish the job. It then retries, and you process the same event twice: two emails, two stock decrements, two ledger entries.

Retries mean duplicates will happen regardless, so you still need to drop events by ID (Handling duplicate webhooks). Responding fast just keeps the number of duplicates low and stops the sender from disabling your endpoint.

The acknowledge-first pattern

  1. Verify the signature against the raw body. If it fails, return 400 and stop.
  2. Store the event (or push it to a queue) keyed by its ID.
  3. Return 2xx.
  4. A separate worker picks the event up and does the actual work.

Verification stays before the acknowledgement so you don't store forged requests. Everything slow (calling other APIs, sending email, recalculating totals) goes after step 3.

Here's an Express handler using the Standard Webhooks library and BullMQ:

import express from 'express';
import { Webhook } from 'standardwebhooks';
import { Queue } from 'bullmq';

const wh = new Webhook(process.env.WEBHOOK_SECRET!); // whsec_…
const queue = new Queue('webhooks', { connection: { host: 'localhost', port: 6379 } });
const app = express();

app.post('/webhooks', express.raw({ type: 'application/json' }), async (req, res) => {
  let event: unknown;
  try {
    event = wh.verify(req.body, req.headers as Record<string, string>);
  } catch {
    return res.sendStatus(400);
  }
  // Using webhook-id as jobId: a retry with the same ID isn't enqueued twice while the job exists
  await queue.add('handle', event, { jobId: String(req.headers['webhook-id']) });
  res.sendStatus(204);
});

app.listen(3000);
Enter fullscreen mode Exit fullscreen mode

And the same shape in FastAPI, writing to an inbox table instead of a queue:

import os
from fastapi import FastAPI, Request, Response
from standardwebhooks import Webhook

wh = Webhook(os.environ["WEBHOOK_SECRET"])
app = FastAPI()

@app.post("/webhooks")
async def webhooks(request: Request):
    body = await request.body()  # raw bytes
    try:
        wh.verify(body, dict(request.headers))
    except Exception:
        return Response(status_code=400)
    await save_inbox(request.headers["webhook-id"], body)  # primary key on the ID
    return Response(status_code=204)
Enter fullscreen mode Exit fullscreen mode

A worker reads unprocessed inbox rows, handles them, and marks them done. If you don't run a queue, this table does the same job, and the primary key doubles as your duplicate check.

Once you've returned 2xx, the sender considers the event delivered. Failures in the worker are invisible to it, so make sure events that exhaust your own retries end up somewhere you'll see them: a failed-jobs table, an alert, a dashboard.

Serverless: the response can be the end of the process

Some serverless runtimes stop your code once the response is sent, or give it a hard budget. "Return 2xx, then keep working in the same function" can silently lose work there.

  • Cloudflare Workers: ctx.waitUntil() keeps work running after the response, but for HTTP-triggered Workers only for up to 30 seconds. Cloudflare's docs say to send longer work to a Queue and process it in a consumer Worker (Cloudflare Context API, checked 2026-09-27).
  • Vercel Functions: promises passed to waitUntil() share the function's timeout and are cancelled if it times out. On Next.js 15.1+, Vercel recommends after() from next/server (@vercel/functions reference, checked 2026-09-27).

Both are fine for short follow-up tasks, but neither retries on failure. If losing the work would matter, enqueue it or write it to a table before you acknowledge.

Choosing the status code

Pair the timeout budget with deliberate status codes (more in Webhook response status codes):

  • Stored successfully: 200 or 204, empty body is fine.
  • Signature mismatch: 400 or 401. Retrying won't fix it, and a visible failure on the sender's side gets noticed sooner.
  • Your own transient failure (database down): 5xx, so the sender retries.
  • Duplicate: 2xx.

Checklist

  • What the endpoint does inline (verify, store, acknowledge) and what it defers
  • Where deferred work goes (queue, inbox table, waitUntil) and how failures there are retried and surfaced
  • Which ID you deduplicate on (webhook-id, Stripe's event ID, X-Shopify-Webhook-Id)
  • The shortest timeout among the providers you receive from, and a response target well under it

If you're on the other side, sending webhooks to your own customers, the retry schedule itself is covered in Designing webhook retries. Webhook Admin handles the 15-second timeout, retries and delivery logs for you: https://app.webhookadmin.com/signup

Quick FAQ

How fast does my webhook endpoint need to respond?

Faster than the sender's timeout, but aim for under a second. LINE cuts off at 2 seconds, Slack and Zoom at 3, Shopify at 5 and GitHub at 10. Verifying a signature and writing a row takes well under a second on most stacks.

What happens if my processing fails after I've returned 2xx?

The sender treats the delivery as successful and won't retry, so recovery is your job. Store the payload before acknowledging, and let your queue's retries or a sweep over unprocessed rows pick it up again.

Should I return an error if the event is a duplicate?

No. Return 2xx for duplicates. A 4xx or 5xx tells the sender the delivery failed, and it will keep retrying the same event.


Thanks for reading! Has a sender's timeout ever forced you to restructure a handler? Tell us in the comments.

This post first appeared on the Webhook Admin blog.

Top comments (0)