Webhook Verification

Overview

The Webhook Verification module authenticates that webhook requests sent to your HTTP endpoints are originated by your webhook provider and intended for you.

See the full list of webhook providers that ngrok supports.

Webhook Verification is important because without it, an attacker could send malicious payloads to your upstream service which could lead to security vulnerabilities or leak confidential data.

Webhook requests that are properly authenticated by the provider will be sent to your upstream service. Other requests will be rejected with an error.

We contribute everything we learn while building this module back to the community at Webhooks.fyi.

Example Usage

Verify that incoming requests are webhooks signed by Twilio for your account.

You can also choose other supported providers like stripe, slack, shopify, github and others.

Agent CLI

ngrok http 80 --verify-webhook twilio --verify-webhook-secret "{twilio webhook secret}"

Agent Config

tunnels:
  example:
    proto: http
    addr: 80
    verify_webhook:
      provider: "twilio"
      secret: "{twilio webhook secret}"

SSH

ssh -R 443:localhost:80 v2@connect.ngrok-agent.com http \
  --verify-webhook twilio \
  --verify-webhook-secret "{twilio webhook secret}"

Go

import (
	"context"
	"net"

	"golang.ngrok.com/ngrok"
	"golang.ngrok.com/ngrok/config"
)

func ngrokListener(ctx context.Context) (net.Listener, error) {
	return ngrok.Listen(ctx,
		config.HTTPEndpoint(
			config.WithWebhookVerification("twilio", "{twilio webhook secret}"),
		),
		ngrok.WithAuthtokenFromEnv(),
	)
}

Go Package Docs:

• https://pkg.go.dev/golang.ngrok.com/ngrok/config#WithWebhookVerification

Javascript

const ngrok = require("@ngrok/ngrok");

(async function () {
	const listener = await ngrok.forward({
		addr: 8080,
		authtoken_from_env: true,
		verify_webhook_provider: "twilio",
		verify_webhook_secret: "{twilio signing secret}",
	});

	console.log(`Ingress established at: ${listener.url()}`);
})();

Javascript SDK Docs:

• https://ngrok.github.io/ngrok-javascript/interfaces/Config.html#verify_webhook_provider
• https://ngrok.github.io/ngrok-javascript/interfaces/Config.html#verify_webhook_secret
• https://ngrok.github.io/ngrok-javascript/classes/HttpListenerBuilder.html#webhookVerification

Python

import ngrok

listener = ngrok.forward("localhost:8080", authtoken_from_env=True,
    verify_webhook_provider="twilio",
    verify_webhook_secret="{twilio signing secret}")

print(f"Ingress established at: {listener.url()}");

Python SDK Docs:

• https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.webhook_verification
• https://ngrok.github.io/ngrok-python/index.html#full-configuration

Rust

use ngrok::prelude::*;

async fn listen_ngrok() -> anyhow::Result<impl Tunnel> {
    let sess = ngrok::Session::builder()
        .authtoken_from_env()
        .connect()
        .await?;
    let tun = sess
        .http_endpoint()
        .webhook_verification("twilio", "{twilio webhook secret}")
        .listen()
        .await?;
    println!("Listening on URL: {:?}", tun.url());
    Ok(tun)
}

Rust Crate Docs:

• https://docs.rs/ngrok/latest/ngrok/config/struct.HttpTunnelBuilder.html#method.webhook_verification

Kubernetes Controller

---
apiVersion: v1
kind: Secret
metadata:
  name: github-webhook-secret
type: Opaque
data:
  secret-token: "<base64-encoded-webhook-secret>"
---
kind: NgrokModuleSet
apiVersion: ingress.k8s.ngrok.com/v1alpha1
metadata:
  name: ngrok-module-set
modules:
  webhookVerification:
    provider: twilio
    secret:
      name: "{twilio webhook secret}"
      key: secret-token
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    k8s.ngrok.com/modules: ngrok-module-set
spec:
  ingressClassName: ngrok
  rules:
    - host: your-domain.ngrok.app
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: example-service
                port:
                  number: 80

Behavior

If a webhook request is verified, it is sent to the upstream service. If it is not, ngrok returns a 403 error response.

If there is provider-specific behavior it will be documented in the provider's integration guide.

Timestamp Tolerance

When a webhook provider provides a mechanism to prevent replay attacks by including a signed timestamp in the webhook, ngrok will reject the webhook request if the difference between the current time and the included timestamp are is outside of tolerance.

If the webhook provider's documentation suggests a tolerance value, we will use that.

Otherwise, ngrok uses a tolerance of 180 seconds.

Endpoint Verification

Some webhook providers require endpoint verification from your application before they will begin sending webhook requests. This helps providers prevent their webhook infrastructure from being used for DOS attacks.

When you configure webhook verification for the following providers, ngrok will automatically handle the endpoint verification request for your application.

• Twitter
• Wordline
• Xero
• Zoom

Reference

Configuration

Parameter	Description
Webhook Provider	The identifier of one of ngrok's supported webhook providers
Webhook Secret	The signing key or secret token which the webhook provider supplied to you for request verification. Consult the guide for your provider to find this value.

Upstream Headers

This module does not add any upstream headers.

Errors

Code	HTTP Status	Error
ERR_NGROK_3204	403	This error is returned if a webhook request fails verification for any reason.

Events

When the Webhook Verification module is enabled, it populates the following fields in the http_request_complete.v0 event:

Fields
webhook_verification.decision

Edges

Webhook Verification is an HTTPS Edge module which can be applied to Routes.

• HTTPS Edge Webhook Verification Module API Resource

Pricing

Webhook Verification usage is calculated account-wide. It is not calculated on a per-endpoint basis.

Plan	Verified Requests
Free	500
Personal	500
Pro	Unlimited
Enterprise	Unlimited

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

Try it out

Consult the comprehensive step-by-step integration guides we've written for every supported provider.