How to Fix & Debug HTTP 504 Gateway Timeout Errors in Webhooks
Resolve HTTP 504 Gateway Timeout webhook failures from Stripe, Shopify, GitHub, and PayPal. Learn why reverse proxies terminate slow handlers and how to implement asynchronous queues.
An HTTP 504 Gateway Timeout error occurs when your edge reverse proxy (Cloudflare, Nginx, AWS ALB) terminates an inbound webhook request because your backend application failed to respond within the allowed timeout window (typically 2 to 5 seconds). The fix is to return a 200 OK immediately and offload payload processing to a background worker queue.
Key Diagnostic Takeaways
- •Cause: Handler took longer than the proxy timeout threshold (typically 2,000–5,000ms).
- •Solution: Acknowledge with HTTP 200 OK immediately before database or external API work.
- •Architecture: Push payloads to Redis, BullMQ, SQS, or RabbitMQ for async consumption.
- •Test: Use SafeWebhook simulated latency slider to verify proxy timeout limits.
Common Root Causes for HTTP 504
Synchronous Heavy Operations in Webhook Handlers
Performing database migrations, generating PDFs, sending transactional emails, or calling third-party APIs synchronously inside the webhook route exceeds the timeout limit.
Cold Starts on Serverless Platforms
AWS Lambda or Vercel Serverless Function cold starts can add 1,500ms to 4,000ms of latency, pushing total response time over the provider threshold.
Database Connection Pool Starvation
Under high webhook volume (e.g. flash sales or mass billing renewals), exhausted database connection pools cause threads to hang until proxies drop the connection.
Provider Retry Schedules for HTTP 504
How major webhook senders retry when receiving status 504:
| Webhook Provider | Retry Schedule & Backoff | Max Window |
|---|---|---|
| Stripe | Exponential backoff over 72 hours (up to 16 attempts) | 3 days |
| Shopify | 19 attempts over 48 hours with 5-minute initial delay | 2 days |
| GitHub | Immediate single retry or manual redelivery in UI | Manual |
| Svix | Configurable retry schedule (up to 10 attempts over 24 hours) | 1 day |
Step-by-Step Resolution Checklist
Production Code Fix Recipe
Node / Express / Python// Solution: Asynchronous Queue Pattern (Express + BullMQ / Redis)
import express from 'express';
import { Queue } from 'bullmq';
const app = express();
const webhookQueue = new Queue('webhook-events', { connection: { host: 'localhost', port: 6379 } });
app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
// 1. Verify cryptographic signature quickly (< 5ms)
const isValid = verifySignature(req.body, req.headers['stripe-signature']);
if (!isValid) return res.status(400).send('Invalid signature');
// 2. Immediately enqueue payload for background worker
await webhookQueue.add('process-event', {
headers: req.headers,
payload: JSON.parse(req.body.toString())
});
// 3. Respond with 200 OK within 20ms to prevent 504 Timeout
res.status(200).json({ received: true });
});How to Test & Simulate HTTP 504 in SafeWebhook
- Open the SafeWebhook Workbench at safewebhook.com/app.
- Go to "Response Config" tab and set Simulated Latency to 4500ms.
- Trigger an event from your webhook provider.
- Observe if your webhook provider marks the delivery as timed out (504).
Frequently Asked Questions: Webhook HTTP 504
Why did my webhook provider disable my endpoint after 504 errors?
Most providers automatically disable webhook endpoints after consecutive timeout failures over several hours to protect their retry pipelines.
Can I return 200 OK before verifying the cryptographic signature?
No. Always verify the signature first to prevent denial-of-service attacks from filling your background queue with forged requests.
Simulate HTTP 504 in 1 Click
Test your application error resilience and webhook retry mechanisms in real-time.