We use Stripe, along with PayPal, to accept payments for our WordPress plugin business. We love Stripe; it’s easy to use and has everything you would want as a developer. While we’ve had many problems with PayPal, Stripe has been pretty flawless. However, as with any service, sometimes issues come up.
Today I’m going to walk you through how to troubleshoot a Stripe webhook error, both TLS and delivery events.
- Stripe webhook delivery issue email
- Checking webhook endpoint events
- How to fix a webhook TLS error
- How to fix webhook being blocked
Stripe webhook delivery issue email
Most of you probably aren’t checking the event log in Stripe regarding webhooks regularly; I know I don’t. Therefore, like me, you probably first hear about a Stripe webhook error in an email from Stripe. It’s then time to drop whatever you’re doing and troubleshoot why the webhook is having a problem. Mine, of course, came in on a Friday afternoon.
The email from Stripe will most likely read something like this below. I’m using a summarized TLS error as an example:
We’ve had some trouble sending requests in live mode to a webhook endpoint associated with your account…
The URL of the failing webhook endpoint is: https://domain.com/index.php?edd-listener=stripe
We’ve attempted to send event notifications to this endpoint x times since the first failure on date/time. If this endpoint is important to your application, please try and fix the issue. We will stop sending event notifications to this webhook endpoint by date/time.”
x requests had a TLS error, indicating that Stripe could not establish a secure connection with your server. You can generate a detailed analysis about your host’s TLS configuration (https://ssllabs.com/ssltest/) to identify common errors.
You need to return any status code between HTTP 200 to 299 for Stripe to consider the webhook event successfully delivered.
You can find the full set of events and request logs on the dashboard.
The Stripe team
The important thing is not to panic. Below I’ll walk you through a couple of easy ways to troubleshoot the issues and some of the things we’ve had to fix with our Stripe implementation.
Checking webhook endpoint events
The very first thing to do is check the events logged for your Stripe webhook endpoints. Go to your Stripe dashboard, and on the left-hand side, click on “Webhooks” under the Developer menu.
On this screen, you’ll be able to see all of your Stripe endpoints and, the most important part, the error rate over the past 7 days. If you just got an email from Stripe saying they’ve tried x number of times to reach your endpoint, then you’ll probably see a pretty high error rate.
If you sort the webhook attempts by “Failed” you can easily see all of the attempts and the reason for failure. Some common Stripe webhook errors include TLS error, timeout, and 500 (internal server error).
How to fix a webhook TLS error
We’ve personally encountered a Stripe webhook TLS error. Here’s what you should do.
- Check your SSL certificate by scanning your site with the SSL Server Test tool from Qualys. The first thing to confirm is that your certificate is valid and that you aren’t missing any intermediate certificates. If you are, try re-adding your SSL certificate with your hosting provider. This is probably one of the most common reasons for a TLS error occurring.
- Confirm the version of TLS your hosting provider supports. Stripe supports up to TLS 1.2 as of writing this.
- If you have a proxy or WAF sitting in front of your website, you’ll need to run through steps 1 and 2 again as Stripe’s webhook will be hitting the proxy/WAF first.
When we encountered our TLS error, the problem was actually due to us moving to Cloudflare. Our Cloudflare domain had the minimum TLS version set to TLS 1.3. (1.0 is the default). Since Stripe only supports up to version 1.2 at the moment, we started encountering a webhook error. It took a while for us to track this down.
How to fix webhook being blocked
Stripe needs to be able to communicate with your server for everything to work properly. So if you’re getting a timeout or even a 500 error, it could be that you’re accidentally blocking Stripe’s webhook. Here’s what you should do.
- If you’re running on WordPress and a security plugin, make sure it’s not blocking any connections from Stripe.
- Check with your hosting provider to make sure they are allowing Stripe and not blocking their IPs.
- If you’re running WAF like Cloudflare, you might need to add an allow rule to the firewall with Stripe’s IPs. Cloudflare’s firewall doesn’t use hostnames, so you will need to use their IPs. I recommend adding both the IPs for api.stripe.com and their webhook notifications. You can check the activity log and compare it against Stripe’s IP list to confirm it’s a Cloudflare issue.
Here is the full expression for the Cloudflare firewall rule with their IPs as of 2021:
(ip.src in 184.108.40.206 220.127.116.11 18.104.22.168 22.214.171.124 126.96.36.199 188.8.131.52 184.108.40.206 220.127.116.11 18.104.22.168 22.214.171.124 126.96.36.199 188.8.131.52 184.108.40.206 220.127.116.11 18.104.22.168 22.214.171.124 126.96.36.199 188.8.131.52 184.108.40.206 220.127.116.11 18.104.22.168 22.214.171.124 126.96.36.199 188.8.131.52 184.108.40.206 220.127.116.11 18.104.22.168 22.214.171.124 126.96.36.199 188.8.131.52 184.108.40.206 220.127.116.11 18.104.22.168 22.214.171.124 126.96.36.199 188.8.131.52 184.108.40.206 220.127.116.11 18.104.22.168 22.214.171.124 126.96.36.199 188.8.131.52 184.108.40.206 220.127.116.11 18.104.22.168 22.214.171.124 126.96.36.199 188.8.131.52 184.108.40.206 220.127.116.11 18.104.22.168 22.214.171.124 126.96.36.199 188.8.131.52 184.108.40.206 220.127.116.11 18.104.22.168 22.214.171.124 126.96.36.199 188.8.131.52 184.108.40.206 220.127.116.11 18.104.22.168 22.214.171.124 126.96.36.199 188.8.131.52 184.108.40.206 220.127.116.11 18.104.22.168 22.214.171.124 126.96.36.199 188.8.131.52 184.108.40.206 220.127.116.11 18.104.22.168 22.214.171.124 126.96.36.199 188.8.131.52 184.108.40.206 220.127.116.11 18.104.22.168 22.214.171.124 126.96.36.199 188.8.131.52 184.108.40.206 220.127.116.11 18.104.22.168 22.214.171.124 126.96.36.199 188.8.131.52 184.108.40.206 220.127.116.11 18.104.22.168 22.214.171.124 126.96.36.199 188.8.131.52 184.108.40.206 220.127.116.11 18.104.22.168 22.214.171.124 126.96.36.199 188.8.131.52 184.108.40.206 220.127.116.11 18.104.22.168 22.214.171.124 126.96.36.199 188.8.131.52 184.108.40.206 220.127.116.11)
Hopefully, some of these tips have been helpful to troubleshoot your Stripe webhook errors. If you have any questions or other steps that have worked for you, I would love to hear them. Drop a comment below.