Documentation Index
Fetch the complete documentation index at: /docs/llms.txt
Use this file to discover all available pages before exploring further.
Skip to main content
Use cases
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.
Copy the HTTPS forwarding URL from the agent console and paste it into your webhook provider’s configuration (for example, Stripe, GitHub, or Twilio).
Then start your endpoint with the policy file:
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
With
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
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 averify-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
ngrok http 8080 --traffic-policy-file /path/to/policy.yml
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, setenforce to false:
policy.yml
on_http_request:
- actions:
- type: verify-webhook
config:
provider: github
secret: your-webhook-secret
enforce: false
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
Theverify-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
Was this page helpful?