Verify Webhook

Overview

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 Directions

• on-http-request

Type

verify-webhook

Configuration Fields

• providerstringRequired

  The name of the provider to verify webhook requests from.

  Value must be a supported provider identifier.

• secretstringRequired

  The secret key used to validate webhook requests from the specified provider.

• enforcebool

  When true, the request will be halted if the webhook is not valid and no further actions will run. However when false, subsequent actions will run even if the webhook was not valid.

  Default true.

Behavior

The verify-webhook action ensures the authenticity of incoming webhook requests by validating their signatures against a known secret. Upon receiving a request, the action performs the signature verification. If verification succeeds, the request proceeds through the action chain. If it fails, the request is terminated 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 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 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

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

Supported Providers

Currently, these integration guides refer to modules.

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 the authenticity of the request using a shared secret. If the request is verified, a custom response is sent back with a status 200 OK and a plain text confirmation message.

Example Traffic Policy Document

YAML

---
on_http_request:
  - 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

{
  "on_http_request": [
    {
      "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.

• actions.ngrok.verify_webhook.verifiedbool

  Indicates whether or not the request was successfully verified.

• actions.ngrok.verify_webhook.error.codestring

  Code for an error that occurred during the invocation of an action.

• actions.ngrok.verify_webhook.error.messagestring

  Message for an error that occurred during the invocation of an action.