# Webhook delivery failed (endpoint returned non-2xx / timed out)

**Code:** `webhook delivery failed` · **Category:** API · **Seen on:** REST API

The provider tried to send a webhook to your endpoint but didn’t get a timely 2xx response, so it marks the delivery failed and retries — eventually disabling the endpoint.

## Meaning

Webhook senders (Stripe, GitHub, Razorpay, Shopify, Twilio) expect a 2xx within a few seconds. Anything else — 3xx redirect, 4xx, 5xx, timeout, TLS error, DNS failure — counts as a failed delivery. After repeated failures many providers disable the endpoint and email you.

Common traps: the URL redirects (http→https, trailing slash, www), a login/CSRF middleware blocks the POST, or the handler does slow work before replying.

## Common causes

- Endpoint returns a redirect (301/302) instead of 2xx
- CSRF, auth or firewall/WAF blocks the provider’s POST
- Handler does slow work synchronously and times out
- Signature check fails so the app returns 400/401
- Endpoint unreachable (localhost URL, expired TLS, DNS)

## Quick fix

1. Return 200 immediately, then process the event in a background job
2. Use the exact final URL (https, correct host, no redirect)
3. Exempt the webhook route from CSRF/login middleware
4. Check the provider’s delivery log for the response code it received

## Detailed fix by platform

### Express

1. 

```bash
app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), (req, res) => {
  const event = stripe.webhooks.constructEvent(req.body, req.headers['stripe-signature'], secret);
  queue.add(event);          // do the work later
  res.sendStatus(200);       // acknowledge fast
});
```


### Laravel

1. 

```bash
// app/Http/Middleware/VerifyCsrfToken.php
protected $except = ['webhooks/*'];
```


## How to diagnose

1. **Delivery log** — Response code/time the provider recorded
2. **Redirects** — curl -I the URL — any 3xx?
3. **Middleware** — CSRF/auth on the route?
4. **Duration** — How long the handler takes

---
Source: [WhatIsMyError](https://whatismyerror.com/errors/api/webhook-delivery-failed)
