What a Stripe webhook does
A webhook is an automated notification that Stripe sends to your WooCommerce site when a payment event occurs. When a customer completes checkout, a payment fails, a hold is captured, or a hold expires, Stripe sends an event to your WooCommerce webhook endpoint.
WooCommerce and plugins like SecureHold WP listen for these events to update order statuses, deposit states and other records. Without a working webhook, some of these updates may not happen in time, or at all.
A webhook can fail silently. Checkout may appear to work correctly while background events that depend on webhook delivery, such as deposit status updates, are not being processed.
A webhook can fail even when checkout appears to work. Always check the endpoint, delivery logs and site accessibility before assuming the payment flow is broken.
Common reasons a Stripe webhook fails
- Wrong endpoint URL. The URL registered in Stripe Dashboard does not match the actual route on your site.
- Mode mismatch. The endpoint was created in test mode but is being used in live mode, or vice versa. Stripe keeps test and live endpoints separate.
- SSL issue. Stripe requires HTTPS. An expired, self-signed or misconfigured SSL certificate will cause delivery to fail.
- Firewall or security plugin blocking requests. Some firewall configurations may block incoming requests from Stripe’s delivery IPs.
- Maintenance mode. If the site returns a maintenance page, Stripe receives a non-200 response and logs a failure.
- Caching or proxy issue. Webhook endpoints should not be cached. Some proxy configurations intercept the request before it reaches WordPress.
- Incorrect signing secret. If the secret configured in the plugin does not match the one on the Stripe endpoint, signature verification fails.
- Missing events. The endpoint was not configured to receive the specific event types the plugin needs.
- Plugin route not registered. If the plugin is deactivated or the route is not set up, WordPress may return a 404 for the endpoint URL.
- Server error on the endpoint. A PHP error or database issue during webhook processing can cause Stripe to treat the delivery as failed.
Step-by-step diagnostic checklist
- 1Open Stripe Dashboard and navigate to Developers, then Webhooks.
- 2Select the webhook endpoint registered for your WooCommerce site.
- 3Review recent delivery attempts and identify the most recent failure.
- 4Check the HTTP status code and error message returned by your server.
- 5Confirm the endpoint URL in Stripe matches the route your plugin expects. If the endpoint is missing or wrong, first set up a Stripe webhook correctly.
- 6Confirm that the mode in Stripe (test or live) matches the mode configured in your plugin.
- 7Run the SecureHold WP Health Check to surface any Stripe or WooCommerce configuration issues.
- 8Create a new test order after fixing the identified issue to confirm webhook delivery is restored.
Understanding webhook HTTP errors
The HTTP status code returned by your server tells you where the failure is happening.
| Error type | What it may mean | What to check |
|---|---|---|
| 400 | Bad request, signing secret mismatch or missing parameters | Webhook signing secret in plugin settings |
| 401 or 403 | Authentication or authorization failure | Firewall rules, HTTP authentication, security plugin settings |
| 404 | Endpoint URL not found on the server | Plugin active, permalink flush, correct endpoint URL in Stripe |
| 500 | Server error during webhook processing | PHP error logs, WooCommerce status, plugin version compatibility |
| Timeout | Server took too long to respond | Server performance, long-running processes on the endpoint |
Test mode vs live mode mistakes
Stripe keeps test and live environments completely separate. Mixing modes is a common source of webhook failures that can be difficult to diagnose.
- Test and live objects are separate. A PaymentIntent created in test mode cannot trigger a live webhook event, and vice versa.
- Webhooks are separate. A test endpoint only receives test events. A live endpoint only receives live events. You need one endpoint per mode.
- API keys are different. Test mode uses test API keys, live mode uses live API keys. Confirm the keys in your plugin settings match the mode you are using.
- Signing secrets are different. Each endpoint in Stripe has its own signing secret. A test endpoint secret will not validate live event signatures.
- Do not mix modes. If your plugin is in live mode but your Stripe endpoint is a test endpoint, or the signing secret does not match, webhook delivery will consistently fail.
Do not ignore webhook failures in Stripe Dashboard. Repeated failures can make WooCommerce payment and deposit workflows unreliable, especially when actions depend on asynchronous payment events.
How SecureHold WP Health Check can help
The SecureHold WP Health Check surfaces common configuration issues that affect deposit and payment workflows.
- Stripe configuration check verifies that API keys and mode settings are correctly configured.
- WooCommerce status review identifies plugin or system conflicts that may affect the webhook endpoint.
- Diagnostics output provides structured information you can share with support if the issue is not immediately clear.
Run Health Check first when diagnosing webhook issues. It may surface the problem faster than manual investigation.
What to send to support
If you have worked through the checklist and the webhook is still failing, gather the following before contacting support.
- The webhook endpoint URL as registered in Stripe Dashboard.
- The most recent delivery error from Stripe, including HTTP status code and response body.
- The WooCommerce order ID or Stripe PaymentIntent ID related to the failing event.
- Your plugin version and WooCommerce version.
- Whether you are in test mode or live mode.
- The output from SecureHold WP Health Check.
- Screenshots from Stripe Dashboard if relevant.
Fix Stripe webhook issues faster
SecureHold WP includes diagnostic tools to help WooCommerce stores identify Stripe, webhook and deposit workflow issues.
FAQ
-
Why is my Stripe webhook not working in WooCommerce?
Common causes include a wrong endpoint URL, a mode mismatch between Stripe and WooCommerce, an SSL issue, a firewall blocking Stripe requests, or an incorrect signing secret. Check the delivery logs in Stripe Dashboard and run the SecureHold WP Health Check to identify the specific problem. -
Can checkout work even if the webhook fails?
Yes. Checkout uses the direct API call, not the webhook. A customer can complete payment successfully even if the webhook is not delivering. However, background events such as payment confirmations, deposit status updates and hold expiry notifications will not be processed until the webhook is fixed. -
How do I know if Stripe can reach my site?
Check the webhook endpoint in Stripe Dashboard under Developers, then Webhooks. Select the endpoint and review recent delivery attempts. Stripe shows the HTTP status code and response body for each attempt. A 404 usually means the endpoint URL is wrong or the plugin route is not registered. -
Should test mode and live mode have separate webhooks?
Yes. Stripe keeps test and live environments separate. A test endpoint only receives test events, and a live endpoint only receives live events. You need a separate webhook endpoint configured for each mode you use, with its own signing secret. -
What should I send to support for webhook issues?
Include the endpoint URL, the most recent Stripe delivery error, the relevant order or PaymentIntent ID, your plugin version, the mode you are using (test or live), and the output from the SecureHold WP Health Check.
