STRIPE WEBHOOKS

Stripe webhook not firing or failing: find the cause in five minutes

Short answer: open the event in Stripe and read the delivery attempt. Stripe records an HTTP status code or an error label for every attempt, and that one line tells you which of a handful of problems you have. Do this before changing any code.

Stripe's webhook documentation is thorough but it is written for developers building a handler. If a tool like Zapier, a plugin or a developer set the webhook up for you, the same table still applies. You just read it and hand the answer to whoever owns the endpoint.

Step 1: look at the delivery in Stripe

In the Stripe Dashboard open Workbench, go to Webhooks, select your endpoint, and open the Event deliveries tab. Stripe lists each event as Delivered, Pending or Failed. Click one to see the HTTP status code of the attempt and, for pending ones, the time of the next retry.

If the event is not in the list at all, it may be a setup issue on the Stripe side rather than your server. Go to Step 2. If it is there and failed, go to Step 3.

Step 2: the event never appears

• The event type is not selected. Each endpoint only receives the event types you chose when you created it. Open the endpoint and check that the event you are waiting for is in the list. Stripe also recommends listening only to the types you need, so do not just tick everything.
• Wrong mode. Sandbox and live mode are separate. An endpoint created in one will not receive events from the other. Check that the endpoint, the keys and the action you took are all in the same mode. We are inferring this from how Stripe separates sandbox retries and live retries in its docs, so confirm in your own Dashboard.
• Wrong account. Our suggestion: check the endpoint is registered on the Stripe account where the payment happened.

Step 3: read the status and fix that one thing

Stripe publishes a table of statuses. This is the practical version:

• Unable to connect. Stripe cannot reach your server. The host must be publicly accessible on the internet, and registered endpoints must be public HTTPS URLs. A localhost address or a site behind a login will not work.
• 3xx, such as 302. Stripe treats a redirect as a failure. A common cause is the site redirecting from http to https or from non-www to www. Register the final URL that the redirect lands on.
• 4xx, such as 400, 401, 403, 404, 405. The server refused or does not know the URL. Stripe says to make sure the endpoint is publicly accessible and accepts the POST method. A 404 can point to a typo in the path or a removed plugin, and a 403 to a firewall or security plugin blocking Stripe. Stripe does not say so, that is our reading, so check your own setup.
• 5xx. Your server hit an error while processing. Look at the server or application logs for what it was.
• TLS error. Stripe could not make a secure connection, usually because of a certificate or intermediate certificate problem. Stripe requires TLS 1.2 or higher. Run an SSL server test on the domain.
• Timed out. The server took too long. Stripe says to defer complex logic and return a success response straight away.

Step 4: signature errors

If your own code or a plugin checks the Stripe-Signature header and rejects the request, you will often see a 400 and a signature verification message in your logs, depending on how the handler was written. Stripe lists these requirements:

• Use the signing secret for that exact endpoint. It starts with whsec_ and is shown on the endpoint page.
• A secret from the Stripe CLI test listener is different from the one for your registered endpoint.
• Stripe needs the raw body of the request to verify the signature. Frameworks and security tools that change the body, for example by parsing it first, make verification fail.

Step 5: understand what Stripe does next

Do not panic if one delivery failed. In live mode Stripe retries for up to three days with exponential back off. Sandbox events are retried three times over a few hours. If you disable or delete the endpoint, Stripe stops retrying those events.

To send an event again yourself, click Resend on the event in the Dashboard (works for up to 15 days after the event was created) or run stripe events resend <event_id> --webhook-endpoint=<endpoint_id> in the Stripe CLI (up to 30 days). Stripe notes that a manual resend does not cancel the automatic retries, even if it returns a 2xx.

Also expect two things that look like bugs but are not. Stripe does not guarantee the order of events, and the same event can arrive more than once. A handler that needs a payment record before an invoice record will sometimes break, and one that does not track event IDs may do the work twice.

Step 6: test it properly

Trigger an event of a type the endpoint listens to. Stripe's example is the CLI command stripe trigger payment_intent.succeeded. Then check Event deliveries again for a 200. Stripe also says an endpoint you are still building can use HTTP on a local machine with the CLI, but a live one must be HTTPS.

One limit worth knowing: Stripe allows up to 16 event destinations. If you have lots of old tools registered, an old unused one may be the one you are looking at.

When to hire help

Bring someone in when the status code tells you the cause but you do not control the endpoint, when a plugin or automation tool sits in the middle, or when payments are going through but orders, emails or access are not being created. That last one costs you money every day.

Send us the store or site address, the name of the event, and the status code from Event deliveries. We will tell you what we found and agree the price before we change anything. A single defined defect is a fixed $299, with the $99 diagnosis credited toward it. Bigger problems get a written quote. We never ask for your password or your secret keys: tell us what is happening.