> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Test Webhooks Locally

> Use ngrok to receive webhook callbacks from third-party services directly on your local development machine.

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

1. [Install ngrok](https://ngrok.com/download)
2. Start your local webhook handler on any port
3. Run `ngrok http <port>` to create a public URL
4. Register the ngrok URL with your webhook provider
5. Receive webhook events directly on your local machine

## Quick example

```bash theme={null}
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](/guides/share-localhost/inspection) 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](/guides/share-localhost/inspection.mdx#how-replays-work) 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](/traffic-policy/actions/verify-webhook/) 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:

```yaml title="policy.yml" theme={null}
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:

```bash theme={null}
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`:

```yaml title="policy.yml" {6} theme={null}
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](/traffic-policy/actions/verify-webhook/#action-result-variables) in subsequent actions.

### Supported providers for webhook verification

The `verify-webhook` action supports [many providers](/traffic-policy/actions/verify-webhook/#supported-providers), including GitHub, Stripe, Shopify, Slack, and Twilio.

## Next steps

* [Verify webhooks](/traffic-policy/actions/verify-webhook) using your signing key
* [Inspect requests and responses](/guides/share-localhost/inspection) in real-time
* Browse [webhook integration guides](/integrations/) for provider-specific setup instructions