How to Verify Webhook Signatures

The verifySignature function works with any supported provider. It accepts a request object (with body and headers fields) and returns { valid: boolean }.

import { verifySignature } from "@webhooks-cc/sdk";
 
// Works with any Request-like object that has body and headers
const result = await verifySignature(request, {
  provider: "stripe",
  secret: process.env.STRIPE_WEBHOOK_SECRET!,
});
 
if (!result.valid) {
  return new Response("Invalid signature", { status: 401 });
}
 
// Signature verified — safe to process the payload
const body = JSON.parse(request.body);

Replace "stripe" with any supported verification provider name: "github", "shopify", "twilio", "slack", "paddle", "linear", "clerk", "discord", "vercel", "gitlab", "typeform", "standard-webhooks", "meta", "lemonsqueezy", "coinbase-commerce", "razorpay", "cal", "intercom", "telegram", "square", "hubspot", "mailgun", "calendly", "mux", "sentry", or "bitbucket".

When a handler receives traffic from several providers, use detectWebhookInfo to pick the right verification branch. Detection is based on headers first, then body shape for providers like SendGrid.

import { detectWebhookInfo, verifySignature } from "@webhooks-cc/sdk";
 
const info = detectWebhookInfo(request);
 
if (info?.provider === "typeform") {
  const result = await verifySignature(request, {
    provider: "typeform",
    secret: process.env.TYPEFORM_WEBHOOK_SECRET!,
  });
 
  if (!result.valid) {
    return new Response("Invalid signature", { status: 401 });
  }
}

When you know the provider at build time, use the dedicated function. These accept the raw body, signature header value, and secret as separate arguments, and return a plain boolean.

import { verifyStripeSignature } from "@webhooks-cc/sdk";
 
const valid = await verifyStripeSignature(
  request.body, // raw body string
  request.headers["stripe-signature"], // signature header value
  process.env.STRIPE_WEBHOOK_SECRET! // your signing secret
);
 
if (!valid) {
  return new Response("Invalid signature", { status: 401 });
}

Provider-specific functions are available for all supported providers: verifyStripeSignature, verifyGitHubSignature, verifyShopifySignature, verifyTwilioSignature, verifySlackSignature, verifyPaddleSignature, verifyLinearSignature, verifyClerkSignature, verifyDiscordSignature, verifyVercelSignature, verifyGitLabSignature, verifyTypeformSignature, verifyStandardWebhookSignature, verifyMetaSignature, verifyLemonSqueezySignature, verifyCoinbaseCommerceSignature, verifyRazorpaySignature, verifyCalSignature, verifyIntercomSignature, verifyTelegramSignature, verifySquareSignature, verifyHubSpotSignature, verifyMailgunSignature, verifyCalendlySignature, verifyMuxSignature, verifySentrySignature, verifyBitbucketSignature. SendGrid is excluded because it uses IP allowlisting instead of cryptographic signatures.

Discord does not use HMAC. Pass publicKey instead of secret. The key is your Discord application's hex-encoded public key from the developer portal.

import { verifySignature } from "@webhooks-cc/sdk";
 
const result = await verifySignature(request, {
  provider: "discord",
  publicKey: process.env.DISCORD_PUBLIC_KEY!,
});
 
if (!result.valid) {
  return new Response("Invalid signature", { status: 401 });
}

Or use the provider-specific function, which takes the body, full headers object, and public key:

import { verifyDiscordSignature } from "@webhooks-cc/sdk";
 
const valid = await verifyDiscordSignature(
  request.body,
  request.headers,
  process.env.DISCORD_PUBLIC_KEY!
);

Twilio's signature covers the full callback URL concatenated with sorted form parameters, not just the body. You must pass the exact URL Twilio was configured to call.

import { verifySignature } from "@webhooks-cc/sdk";
 
const result = await verifySignature(request, {
  provider: "twilio",
  secret: process.env.TWILIO_AUTH_TOKEN!,
  url: "https://your-app.com/api/webhooks/twilio",
});
 
if (!result.valid) {
  return new Response("Invalid signature", { status: 401 });
}

Without the url option, verification throws an error.

Slack sends two headers: x-slack-signature and x-slack-request-timestamp. The SDK reconstructs the base string as v0:{timestamp}:{body} and computes HMAC-SHA256.

import { verifySlackSignature } from "@webhooks-cc/sdk";
 
// Slack-specific function takes the body, full headers object, and secret
const valid = await verifySlackSignature(
  request.body,
  request.headers,
  process.env.SLACK_SIGNING_SECRET!
);

Slack rejects signatures when the timestamp is older than 5 minutes. If you are verifying captured webhooks, verify promptly after capture.

Clerk uses the Standard Webhooks (Svix) signing format. The SDK provides a dedicated "clerk" provider that delegates to Standard Webhooks verification.

const result = await verifySignature(request, {
  provider: "clerk",
  secret: process.env.CLERK_WEBHOOK_SECRET!,
});

Vercel signs deploy hook payloads with HMAC-SHA1 and sends the hex-encoded signature in the x-vercel-signature header.

const result = await verifySignature(request, {
  provider: "vercel",
  secret: process.env.VERCEL_WEBHOOK_SECRET!,
});

GitLab sends the configured webhook token verbatim in the x-gitlab-token header. The SDK performs a constant-time comparison against your secret.

const result = await verifySignature(request, {
  provider: "gitlab",
  secret: process.env.GITLAB_WEBHOOK_TOKEN!,
});

Typeform signs the exact raw JSON payload with HMAC-SHA256 and sends the base64 signature in the typeform-signature header with a sha256= prefix.

const result = await verifySignature(request, {
  provider: "typeform",
  secret: process.env.TYPEFORM_WEBHOOK_SECRET!,
});

Standard Webhooks uses three headers: webhook-id, webhook-timestamp, and webhook-signature. Many services use this spec, including Polar.sh, Svix, Resend, Liveblocks, and Novu.

import { verifySignature } from "@webhooks-cc/sdk";
 
const result = await verifySignature(request, {
  provider: "standard-webhooks",
  secret: process.env.POLAR_WEBHOOK_SECRET!,
});

Secrets with a whsec_ prefix are handled automatically. The SDK detects whether the key after the prefix is base64-encoded (Svix) or raw UTF-8 (Polar.sh).

Meta signs the raw body with HMAC-SHA256 and sends sha256={hex} in x-hub-signature-256 — the same scheme as GitHub — keyed by your app secret. Because Meta shares GitHub's header, configure meta explicitly rather than relying on header auto-detection.

const result = await verifySignature(request, {
  provider: "meta",
  secret: process.env.META_APP_SECRET!,
});

These providers each send a raw hex HMAC-SHA256 of the body in their own header — x-signature (Lemon Squeezy), x-cc-webhook-signature (Coinbase Commerce), x-razorpay-signature (Razorpay), and x-cal-signature-256 (Cal.com). Pass the matching provider id:

const result = await verifySignature(request, {
  provider: "coinbase-commerce",
  secret: process.env.COINBASE_COMMERCE_WEBHOOK_SECRET!,
});

Intercom signs the raw body with HMAC-SHA1 and sends sha1={hex} in the x-hub-signature header, keyed by your app's client secret. The sha1= prefix distinguishes it from GitHub (x-hub-signature-256) and Bitbucket (sha256=).

const result = await verifySignature(request, {
  provider: "intercom",
  secret: process.env.INTERCOM_CLIENT_SECRET!,
});

Telegram does not use HMAC. It echoes the secret_token you registered with setWebhook verbatim in the x-telegram-bot-api-secret-token header. The SDK performs a constant-time comparison against your secret.

const result = await verifySignature(request, {
  provider: "telegram",
  secret: process.env.TELEGRAM_WEBHOOK_SECRET_TOKEN!,
});

Square and HubSpot mix request context into the signed payload, so verification needs more than the body and secret.

Square signs the notification URL concatenated with the raw body (base64 HMAC-SHA256 in x-square-hmacsha256-signature). Pass the exact URL Square delivers to via the url option:

const result = await verifySignature(request, {
  provider: "square",
  secret: process.env.SQUARE_SIGNATURE_KEY!,
  url: "https://your-app.com/api/webhooks/square",
});

HubSpot v3 signs {method}{url}{body}{timestamp} (base64 HMAC-SHA256 in x-hubspot-signature-v3, with the millisecond timestamp in x-hubspot-request-timestamp). Pass both url and method. HubSpot also rejects signatures whose timestamp is more than 5 minutes old, so verify promptly after capture:

const result = await verifySignature(request, {
  provider: "hubspot",
  secret: process.env.HUBSPOT_CLIENT_SECRET!,
  url: "https://your-app.com/api/webhooks/hubspot",
  method: "POST",
});

Without the required url option, verification throws an error for both providers. method defaults to "POST" when omitted for HubSpot.

Mailgun is the only supported provider with no signature header. It embeds the signature in the request body under signature.{timestamp,token,signature} and signs {timestamp}{token} with HMAC-SHA256 (hex). The SDK reads the body directly and returns false (never throws) on malformed input:

const result = await verifySignature(request, {
  provider: "mailgun",
  secret: process.env.MAILGUN_SIGNING_KEY!,
});

Calendly and Mux both use the Stripe-style t=<timestamp>,v1=<hash> header format — calendly-webhook-signature and mux-signature respectively — computing HMAC-SHA256 over {timestamp}.{body} (hex):

const calendly = await verifySignature(request, {
  provider: "calendly",
  secret: process.env.CALENDLY_SIGNING_KEY!,
});
 
const mux = await verifySignature(request, {
  provider: "mux",
  secret: process.env.MUX_SIGNING_SECRET!,
});

Sentry signs the raw body with HMAC-SHA256 and sends the hex digest in sentry-hook-signature. The resource type travels in sentry-hook-resource:

const result = await verifySignature(request, {
  provider: "sentry",
  secret: process.env.SENTRY_CLIENT_SECRET!,
});

Bitbucket signs the raw body with HMAC-SHA256 and sends sha256={hex} in the x-hub-signature header — the same scheme as GitHub. Auto-detection distinguishes it from Intercom (which also uses x-hub-signature, but with sha1=) by Bitbucket's unique x-event-key header:

const result = await verifySignature(request, {
  provider: "bitbucket",
  secret: process.env.BITBUCKET_WEBHOOK_SECRET!,
});