Testing Stripe webhooks locally with expose.sh

By Robbie | July 15, 2020

Introduction

Lets say I’m selling products online using Stripe and I want to receive webhook notifications for important events like customer trial expiry, payment intents etc.

I’ve written an endpoint for Stripe to send webhook notifications to. Normally with webhooks, to test my endpoint end to end under realistic production like conditions I’d need to deploy my server somewhere public so Stripe can see it.

That’s a lot of work and I’m feeling lazy. So instead I’m going to run my service locally and use Expose.sh to give it a public URL that Stripe can then send Webhook requests to.

By testing my webhook endpoint locally i’ll also have access to all of my debugging tools and be able to quickly fix issues without having to deploy code to a remote public facing server, saving whole lot of time and effort.

How can you do this yourself?

Install expose.sh

For Mac or Linux, go to Expose.sh and copy/paste the installation code shown into a terminal.

For Windows go to Expose.sh, download the binary and put it somewhere in your PATH.

Expose your api to the web

Start your API server. Then run expose <port> where port is the port your API server is running on, like 80 or 8080.

Expose.sh will generate a random public expose.sh URL. You’ll see output like

https://s3rh.expose.sh is forwarding to localhost:80
http://s3rh.expose.sh is forwarding to localhost:80

Configure Stripe to ping your webhook endpoint using your new expose.sh URL

I have an endpoint set up to receive Stripe webhook requests at /api/v1/stripe/webhook-receive. I’m going to set this up in Stripe and then trigger Stripe to send me a simulated notification using the Stripe CLI tool as a first test, then I’m going to trigger a real Stripe webhook request to go to my local server.

As a test, I’m going to trigger Stripe to send me the payment_intent.created webhook request. This can be done with the Stripe CLI tool. Set it up with stripe listen --forward-to https://s3rh.expose.sh/api/v1/stripe/webhook-receive. Replacing the url for the --forward-to parameter with your expose.sh url + endpoint.

Then run stripe trigger payment_intent.created

Feel free to set debug breakpoints or add logging to your code so you can see the details of whats happening.

The Stripe will hit your endpoint, which is running on your local machine. You can then debug and make changes as needed.

While the Stripe CLI can forward to localhost also, it does not support all events. For example, it doesn’t yet support customer.subscription.trial_will_end or any other events that aren’t directly triggered by an API request. For these events, you can still test them locally by starting your server, exposing it to the web with expose.sh, then performing an action (for example, make a payment or create a subscription) that will trigger the webhook notification to your event.

First you’ll need to set up your expose.sh webhook endpoint in the Stripe Dashboard here.

Click “Add endpoint” in the top right hand corner of your screen: Stripe webhook settings

Then configure your endpoint and select the events you want to receive notifications for: Set up trigger

Now perform the action that will trigger your webhook. Stripe will now hit your webhook endpoint which is running locally, exposed via expose.sh.

Custom expose.sh subdomains

Using a custom subdomain (like myapi.expose.sh) would save you from needing to enter in or reconfigure a different URL each time.

Expose.sh is free to use for randomly generated subdomains. If you want to use your own custom subdomains like “myapi.expose.sh”, you can do this for as little as $5/month depending on how many domains you want to use. Its usually a good time vs money investment, considering the hourly rate of most people who use expose.sh for work. Sign up here.

Conclusion

As you can see, using expose.sh to test your Stripe webhook integration is much faster than doing it using a remote server and can be used with all Stripe webhooks, not just the small subset supported by Stripe CLI. Expose.sh is free to use for random subdomains. You can use custom domains for as little as $4.99 per month.

Happy coding!

Get started here