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. It also prevents replay attacks when supported by the provider.

It is configured with a provider name and a secret key given to you by the provider.

Webhook Verification is important because without it, an attacker could send malicious payloads to your application 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 application. Other requests will be rejected with an error.

We've written integration guides for every supported provider to make it easy for you to set up because there is little standardization among providers.

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

Quickstart

Agent CLI

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

Agent Configuration File

tunnels:
  example:
    proto: http
    addr: 80
    verify_webhook:
      provider: "twilio"
      secret: "{twilio-auth-token}"

SSH

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

Go SDK

import (
    "context"
    "net"

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

func listenWebhookVerification(ctx context.Context) net.Listener {
    listener, _ := ngrok.Listen(ctx,
        config.HTTPEndpoint(
            config.WithWebhookVerification("shopify", "{shopify app client secret}"),
        ),
        ngrok.WithAuthtokenFromEnv(),
    )
    return listener
}

Rust SDK

use ngrok::prelude::*;

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

Kubernetes Ingress 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: github
    secret:
      name: "{github 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

Edges

Webhook Verification is a supported module for HTTPS edges. It is attached to an edge route. Like all edge modules, it can be configured via API.

• HTTPS Edge Webhook Verification Module API Resource

Behavior

If a webhook request is verified, it is sent to the upstream server. 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

Limits

Webhook Verification limits are enforced account-wide, they are not specific to an endpoint.

Plan	Verified Requests
Free	500
Personal	500
Pro	Unlimited
Enterprise	Unlimited

Supported Providers

Provider	Provider Identifier	Integration Guide
AfterShip	aftership	Documentation
Airship	airship	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
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.