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 validates that incoming webhook requests are authentic. When a request is received, the action verifies the request by validating its signature against a known secret. If the verification is successful, the action allows the request to continue through the action chain and to finally to your application; if verification fails, the request will be terminated with a 403 Forbidden response.

Verification Process

• Signature Validation: The action validates incoming webhook signature to confirm 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 action. 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 allows unverified requests to proceed, while logging the verification result. This option is for debugging and testing.

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

All secrets used for webhook verification are encrypted at config validation. When ngrok processes a requests the secret is decrypted.

Supported Providers

Provider	Provider Identifier	Integration Guide
AfterShip	aftership	Documentation
Airship	airship	Documentation
Alchemy	alchemy	Documentation
Amazon SNS	sns	Documentation
Autodesk Platform Services	autodesk	Documentation
Bitbucket	bitbucket	Documentation
Bolt	bolt	Documentation
Box	box	Documentation
Brex	brex	Documentation
Buildkite	buildkite	Documentation
Calendly	calendly	Documentation
Castle	castle	Documentation
Chargify	chargify	Documentation
CircleCI	circleci	Documentation
Clearbit	clearbit	Documentation
Clerk	clerk	Documentation
Coinbase	coinbase	Documentation
Contentful	contentful	Documentation
DocuSign	docusign	Documentation
Dropbox	dropbox	Documentation
Facebook Graph API	facebook_graph_api	Documentation
Facebook Messenger	facebook_messenger	Documentation
Frame.io	frameio	Documentation
GitHub	github	Documentation
GitLab	gitlab	Documentation
Go1	go1	Documentation
Heroku	heroku	Documentation
Hosted Hooks	hostedhooks	Documentation
HubsSpot	hubspot	Documentation
Hygraph (Formerly GraphCMS)	graphcms	Documentation
Instagram	instagram	Documentation
Intercom	intercom	Documentation
Launch Darkly	launch_darkly	Documentation
Mailchimp	mailchimp	Documentation
Mailgun	mailgun	Documentation
Microsoft Teams	microsoft_teams	Documentation
Modern Treasury	modern_treasury	Documentation
MongoDB	mongodb	Documentation
Mux	mux	Documentation
Orb	orb	Documentation
Orbit	orbit	Documentation
PagerDuty	pagerduty	Documentation
Pinwheel	pinwheel	Documentation
Plivo	plivo	Documentation
Pusher	pusher	Documentation
SendGrid	sendgrid	Documentation
Sentry	sentry	Documentation
Shopify	shopify	Documentation
Signal Sciences	signal_sciences	Documentation
Slack	slack	Documentation
Sonatype Nexus	sonatype	Documentation
Square	square	Documentation
Stripe	stripe	Documentation
Svix	svix	Documentation
Terraform	terraform	Documentation
TikTok	tiktok	Documentation
Trend Micro Conformity	trendmicro_conformity	Documentation
Twilio	twilio	Documentation
Twitter	twitter	Documentation
Typeform	typeform	Documentation
VMware Workspace	vmware	Documentation
Webex	webex	Documentation
WhatsApp	whatsapp	Documentation
Worldline	worldline	Documentation
Xero	xero	Documentation
Zendesk	zendesk	Documentation
Zoom	zoom	Documentation

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!'
> 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.