How to fix a Stripe webhook error (TLS and delivery events)

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

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.

Yours,
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.

Stripe endpoints error rate
Stripe endpoints 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).

Stripe webhook attempts
Stripe webhook attempts

How to fix a webhook TLS error

We’ve personally encountered a Stripe webhook TLS error. Here’s what you should do.

  1. 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.
  2. Confirm the version of TLS your hosting provider supports. Stripe supports up to TLS 1.2 as of writing this.
  3. 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.

Cloudflare minimum TLS version
Cloudflare minimum TLS version

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.

  1. If you’re running on WordPress and a security plugin, make sure it’s not blocking any connections from Stripe. 
  2. Check with your hosting provider to make sure they are allowing Stripe and not blocking their IPs.
  3. 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.
Cloudflare firewall rule for Stripe IPs
Cloudflare firewall rule for Stripe IPs

Here is the full expression for the Cloudflare firewall rule with their IPs as of 2021: 

(ip.src in {13.112.224.240 13.115.13.148 13.210.129.177 13.210.176.167 13.228.126.182 13.228.224.121 13.230.11.13 13.230.90.110 13.55.153.188 13.55.5.15 13.56.126.253 13.56.173.200 13.56.173.232 13.57.108.134 13.57.155.157 13.57.156.206 13.57.157.116 13.57.90.254 13.57.98.27 18.194.147.12 18.195.120.229 18.195.125.165 34.200.27.109 34.200.47.89 34.202.153.183 34.204.109.15 34.213.149.138 34.214.229.69 34.223.201.215 34.237.201.68 34.237.253.141 34.238.187.115 34.239.14.72 34.240.123.193 34.241.202.139 34.241.54.72 34.241.59.225 34.250.29.31 34.250.89.120 35.156.131.6 35.156.194.238 35.157.227.67 35.158.254.198 35.163.82.19 35.164.105.206 35.164.124.216 50.16.2.231 50.18.212.157 50.18.212.223 50.18.219.232 52.1.23.197 52.196.53.105 52.196.95.231 52.204.6.233 52.205.132.193 52.211.198.11 52.212.99.37 52.213.35.125 52.22.83.139 52.220.44.249 52.25.214.31 52.26.11.205 52.26.132.102 52.26.14.11 52.36.167.221 52.53.133.6 52.54.150.82 52.57.221.37 52.59.173.230 52.62.14.35 52.62.203.73 52.63.106.9 52.63.119.77 52.65.161.237 52.73.161.98 52.74.114.251 52.74.98.83 52.76.14.176 52.76.156.251 52.76.174.156 52.77.80.43 52.8.19.58 52.8.8.189 54.149.153.72 54.152.36.104 54.183.95.195 54.187.182.230 54.187.199.38 54.187.208.163 54.238.140.239 54.65.115.204 54.65.97.98 54.67.48.128 54.67.52.245 54.68.165.206 54.68.183.151 107.23.48.182 107.23.48.232 3.18.12.63 3.130.192.231 13.235.14.237 13.235.122.149 35.154.171.200 52.15.183.38 54.187.174.169 54.187.205.235 54.187.216.72 54.241.31.99 54.241.31.102 54.241.34.107})

Summary

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.

author bio
Brian Jackson

I craft actionable content and develop performance-driven WordPress plugins. Connect on X, subscribe to my newsletter (once a month), or buy me coffee.

2 thoughts on “How to fix a Stripe webhook error (TLS and delivery events)”

Leave a Comment