Skip to main content
The Verify Webhook Traffic Policy action enables you to validate incoming webhook signatures against a known secret to ensure authenticity. Depending on the verification result, it either forwards the request to the next action or rejects it, safeguarding your endpoints from unauthorized or tampered webhooks.

​
Configuration reference

This is the Traffic Policy configuration reference for this action.

​
Supported phases

  • on_http_request

​
Type

verify-webhook

​
Configuration fields

​
Behavior

The verify-webhook action ensures the authenticity of incoming webhook requests by validating their signatures against a known secret. When it receives a request, the action performs the signature verification. If verification succeeds, the request proceeds through the action chain. If it fails, ngrok terminates the request with a 403 Forbidden response, unless enforce is set to false, in which case the request proceeds without termination.

​
Verification process

  • Signature validation: The action validates the incoming webhook signature to confirm the request originates from the configured provider and that no one has tampered with the payload.
  • Request handling: If the webhook verification succeeds, ngrok forwards the request to the next action. If the verification fails, ngrok terminates the request chain with a 403 response.
  • Configurable enforcement: By default, verification failures result in termination. However, setting enforce: false allows unverified requests to proceed, while logging the verification result. This option is useful for debugging, testing, and crafting your own custom responses with action result variables.

​
Endpoint verification

Some webhook providers require an initial endpoint verification challenge to validate that your application is legitimate before sending webhook events. The verify-webhook action automatically handles endpoint verification challenges for supported providers.
  • Supported providers:
    • Twitter
    • Worldline
    • Xero
    • Zoom

​
Replay prevention with timestamp tolerance

To prevent replay attacks, ngrok verifies that the webhook’s timestamp falls within an acceptable range.

​
Secret handling and encryption

ngrok encrypts all secrets used for webhook verification at config validation. When ngrok processes a request, it decrypts the secret.

​
Non-terminating action

This is a Non-terminating action. It does not return a response, and will allow Traffic Policy processing to continue to the next Action in the chain. All Cloud Endpoint Traffic Policies must end with a terminating action. This requirement does not apply to Agent Endpoints.

​
Supported providers

Currently, these integration guides refer to modules.
If you don’t see your preferred webhook provider, you can request support for it.

​
Examples

​
Basic example

This example configuration sets up an endpoint (gitlab-webhook-example.ngrok.app) that receives webhook requests from GitLab. The Verify Webhook action checks the authenticity of the request using a shared secret. If the action verifies the request, ngrok sends back a custom response with a status 200 OK and a plain text confirmation message.

​
Example Traffic Policy document

​
Start endpoint with Traffic Policy

The Verify Webhook action processes this request first. If the GitLab webhook verification succeeds, ngrok returns a 200 OK response with the message GitLab webhook verified.

​
Action result variables

The following variables are made available for use in subsequent expressions and CEL interpolations after the action has run. Variable values will only apply to the last action execution, results are not concatenated.