So you are implementing your webhooks? Sweet. Then you have certainly asked yourself about the best way to test your webhook.

We want to implement, debug and test our webhooks receiver locally in a development environment. If we want to test it locally, we can only test it with the artificial events produced by a mock server. What to do, when we want to test the receiver against some real events from the API provider?

To be able to receive real events from the API provider, the receiver needs to be accessible from the public internet. The developer machine, however, should not be accessible from the internet.

Test the webhook on your local development environment

Ngrok is an excellent tool for testing webhooks.  It exposes local servers behind NATs and firewalls to the public internet via a secure tunnel. Ngrok consists of two components:

  • a cloud component, and
  • a local component that needs to be installed on the local machine.

Between the two components, Ngrok establishes a secure tunnel. The Ngrok cloud component provides a publicly accessible URL. Whatever is sent to that public URL is tunneled to the local installation of Ngrok and made available to the local development server. This setup allows us to make our event receiver endpoint available on the internet and accessible for the event sender, even though it is running on a local development machine.

To set this system up, we need to create an event subscription with the Ngrok URL as the receiver. Now the events arrive from the API provider on our local webhook receiver, where we can test the webhook based on real event data.

Even though this setup is working for development, we need to deploy the receiver for production.

Learn more about Events in RESTful Architectures in the Webhooks Book.

How to test your Webhook

Also published on Medium.

Tagged on:         

Matthias Biehl

As API strategist, Matthias helps clients discover their opportunities for innovation with APIs & ecosystems and turn them into actionable digital strategies. Based on his experience in leading large-scale API initiatives in both business and technology roles, he shares best practices and provides both strategic and practical guidance. He has stayed a techie at heart and at some point, got a Ph.D. Matthias publishes a blog at, is the author of several books on APIs, and regularly speaks at technology conferences.