Test Webhooks Locally - ngrok documentation

Webhooks require a publicly accessible URL, which makes local development tricky. ngrok solves this by giving your local server a public HTTPS endpoint that webhook providers can deliver events to.

How it works

Install ngrok
Start your local webhook handler on any port
Run ngrok http <port> to create a public URL
Register the ngrok URL with your webhook provider
Receive webhook events directly on your local machine

Quick example

ngrok http 8080

Copy the HTTPS forwarding URL from the agent console and paste it into your webhook provider’s configuration (for example, Stripe, GitHub, or Twilio).

Inspect webhook payloads

ngrok’s built-in Traffic Inspector lets you see every webhook request in real time, including headers, body, and response. This makes it easy to debug webhook integrations without adding logging to your application.

Replay failed webhooks

Instead of waiting for the webhook provider to retry a failed delivery, you can replay the request instantly from the Traffic Inspector. This dramatically speeds up the development cycle when building webhook handlers.

Verify webhook signatures

Webhook providers sign each request with a secret so you can confirm it’s authentic. Instead of writing verification logic in your application, you can use the verify-webhook Traffic Policy action to validate incoming webhook signatures and confirm requests originate from the expected provider. Add a verify-webhook action to your Traffic Policy configuration with your provider name and signing secret:

policy.yml

on_http_request:
  - actions:
      - type: verify-webhook
        config:
          provider: gitlab
          secret: secret!
      - type: custom-response
        config:
          status_code: 200
          headers:
            content-type: text/plain
          body: GitLab webhook verified

Then start your endpoint with the policy file:

ngrok http 8080 --traffic-policy-file  /path/to/policy.yml

If verification succeeds, the request proceeds to the next action defined in your Traffic Policy, which in this case will send a custom HTTP response. If it fails, the request is terminated with a 403 Forbidden response.

Debugging

When debugging, testing, and crafting custom responses, you may want to allow further Traffic Policy actions to be processed even if the webhook signature isn’t verified. To do so, set enforce to false:

policy.yml

on_http_request:
  - actions:
      - type: verify-webhook
        config:
          provider: github
          secret: your-webhook-secret
          enforce: false

With enforce: false, unverified requests still reach your server, but you can inspect the verification result using action result variables in subsequent actions.

Supported providers for webhook verification

The verify-webhook action supports many providers, including GitHub, Stripe, Shopify, Slack, and Twilio.

Next steps

Verify webhooks using your signing key
Inspect requests and responses in real-time
Browse webhook integration guides for provider-specific setup instructions

​How it works

​Quick example

​Inspect webhook payloads

​Replay failed webhooks

​Verify webhook signatures

​Debugging

​Supported providers for webhook verification

​Next steps