Verify Webhook

Overview

The Verify Webhook Traffic Policy action enables you to validate incoming webhook signatures against a known secret to ensure authenticity, and either forwards the request to the next action or rejects it based on the verification result.

Configuration Reference

This is the Traffic Policy configuration reference for this action.

Action Type

verify-webhook

Configuration Fields

Parameter	Type	Description
provider	string	Required. The name of the provider to verify webhook requests from. Value must be one of the supported providers.
secret	string	A secret key used to validate requests from the given provider.
enforce	bool	Whether or not the actions is executed (defaults to true)`.

Supported Directions

• on-http-request

Supported Schemes

• https
• http

Behavior

The Verify Webhook action ensures that incoming webhook requests are genuinely sent by the specified webhook provider and are intended for your application. When a webhook request is received, the action verifies the authenticity of the request by validating its signature against a known secret or other security mechanisms provided by the provider. If the verification is successful, the action allows the request to continue through the request chain; if verification fails, the request will be terminated with a 403 Forbidden response.

Verification Process

• Signature Validation: The action validates the incoming webhook signature to confirm that the request originates from the configured provider and that the payload has not been tampered with.
• Request Handling: If the webhook verification is successful, the request is forwarded to the next handler. If the verification fails, the request chain is terminated with a 403 response.
• Configurable Enforcement: By default, verification failures result in termination. However, setting enforce: false in the configuration allows unverified requests to proceed, while logging the verification result. This option provides flexibility for debugging or testing scenarios.

Supported Protocols and Phases

• Protocols: Only HTTP is supported.
• Phases: This action runs in the on_http_request phase, processing incoming HTTP requests.

Endpoint Verification

Some webhook providers require an initial endpoint verification challenge to validate that your application is legitimate before sending webhook events. The ngrok Verify Webhook Action automatically handles endpoint verification challenges from supported providers, ensuring compliance with provider-specific requirements.

• Supported providers for endpoint verification:
  • 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, based on either the provider's recommended tolerance or a default of 180 seconds if unspecified. This helps ensure that requests are timely and reduces vulnerability to replayed payloads.

Secret Handling and Encryption

All secrets used for webhook verification are encrypted at the time of configuration submission. When ngrok processes requests or returns the action configuration via the API or dashboard, the secret is decrypted securely. To protect sensitive information, the secret appears as a redacted value in logs, ensuring confidentiality.

Examples

Basic Example

This example configuration sets up an endpoint (gitlab-webhook-example.ngrok.io) that receives webhook requests from GitLab. The Verify Webhook action checks if the request is authentic based on a shared secret. If verified, a custom response is sent back with a 200 status and a plain text confirmation message.

Example Traffic Policy Document

YAML

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

JSON

{
  "inbound": [
    {
      "actions": [
        {
          "type": "verify-webhook",
          "config": {
            "provider": "gitlab",
            "secret": "secret!"
          }
        },
        {
          "type": "custom-response",
          "config": {
            "status_code": 200,
            "headers": {
              "content-type": "text/plain"
            },
            "content": "GitLab webhook verified"
          }
        }
      ]
    }
  ]
}

Start Endpoint with Traffic Policy

ngrok http 8080 --url gitlab-webhook-example.ngrok.io --traffic-policy-file /path/to/policy.yml

$ curl --location --request POST 'https://gitlab-webhook-example.ngrok.io/' \
--header 'X-Gitlab-Token: secret!'
agent webhooks pog%
 ...
> POST / HTTP/2
> Host: gitlab-webhook-example.ngrok.io
> User-Agent: curl/[version]
> Accept: */*
> X-Gitlab-Token: secret!
...

This request will first be processed by the Verify Webhook action. If the GitLab webhook verification is successful, ngrok will return a 200 OK response with the message GitLab webhook verified.

HTTP/2 200 OK
content-type: text/plain
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.

Name	Type	Description
actions.ngrok.verify_webhook.verified	bool	Was the request verified or not?
actions.ngrok.verify_webhook.error.code	string	Code for an error that occurred during the invocation of an action.
actions.ngrok.verify_webhook.error.message	string	Message for an error that occurred during the invocation of an action.