verifySignature() API Reference (@webhooks-cc/sdk)

Overview

Most webhook providers sign payloads so you can verify authenticity before processing. The SDK includes verification functions for 32 signed providers, plus a generic verifySignature that dispatches by provider name. For a conceptual walkthrough of HMAC-SHA256, Ed25519, and RSA webhook verification in Express and Next.js handlers, see the How to Verify Webhook Signatures guide. SendGrid is supported for templates and detection; SendGrid signs Event Webhooks with ECDSA (X-Twilio-Email-Event-Webhook-Signature), which the SDK does not currently verify. Plaid is template-only for now because verification needs Plaid JWT/JWK lookup credentials.

Requests and emails that webhooks.cc forwards to your server have their own verifiers: verifyRelayedRequest for requests relayed as received, verifyForwardedRequest and verifyForwardedEmail for signed JSON. See Forwarded requests and Forwarded emails.

Generic verifier (works with any supported provider):

import { verifySignature } from "@webhooks-cc/sdk";

Provider-specific verifiers (when you know the provider at build time):

import {
  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,
  verifyDocuSignSignature,
  verifyAdyenSignature,
  verifyPayPalSignature,
  verifyResendSignature,
  verifyWorkOSSignature,
} from "@webhooks-cc/sdk";

Server-side verification

When you configure a signing secret on an endpoint (via the dashboard or SDK), the server verifies every incoming webhook automatically and stores the result on the request:

import { matchAll, matchMethod, matchVerified } from "@webhooks-cc/sdk";
 
const req = await client.requests.waitFor(slug, {
  match: matchAll(matchMethod("POST"), matchVerified()),
  timeout: "30s",
});
 
console.log(req.signatureVerified); // true
console.log(req.signingProvider); // "stripe"

Configure signing via the SDK:

await client.endpoints.update(slug, {
  signingProvider: "stripe",
  signingSecret: "whsec_...",
});

Clear it:

await client.endpoints.update(slug, {
  signingProvider: null,
});

The request object includes three verification fields:

Client-side verification

The SDK also includes client-side verification functions that work without server-side configuration. These are useful in your own webhook handlers:

Provider reference

Stripe

Stripe uses a t=timestamp,v1=hash format in the stripe-signature header. The SDK parses the header, reconstructs the signed payload as {timestamp}.{body}, and compares the HMAC-SHA256 hash.

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

GitHub

GitHub sends a sha256=hash value in x-hub-signature-256. The SDK computes HMAC-SHA256 over the raw body and compares.

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

Shopify

Shopify sends a base64-encoded HMAC-SHA256 hash in x-shopify-hmac-sha256. The SDK computes the hash over the raw body and compares the base64 output.

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

Twilio

Twilio signs using HMAC-SHA1 over the full callback URL concatenated with sorted form parameters. The signature is base64-encoded and sent in x-twilio-signature.

const result = await verifySignature(request, {
  provider: "twilio",
  secret: process.env.TWILIO_AUTH_TOKEN!,
  url: "https://example.com/api/twilio/webhook",
});

Without the url option, verification throws an error.

Slack

Slack sends two headers: x-slack-signature (format v0=hash) and x-slack-request-timestamp. The SDK constructs the base string as v0:{timestamp}:{body} and computes HMAC-SHA256.

Slack rejects signatures when the timestamp is older than 5 minutes, so verify promptly after capture.

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

Paddle

Paddle uses a two-part signature format: ts=timestamp;h1=hash in the paddle-signature header. The SDK parses both parts, reconstructs the signed payload as {timestamp}:{body}, and compares the HMAC-SHA256 hash.

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

Linear

Linear sends an HMAC-SHA256 hash in the linear-signature header, optionally prefixed with sha256=. The SDK handles both formats.

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

Clerk

Clerk uses the Standard Webhooks (Svix) signing format. The SDK provides a dedicated verifyClerkSignature that delegates to Standard Webhooks verification using the Clerk-specific headers.

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

Vercel

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

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

GitLab

GitLab uses raw token comparison rather than HMAC. The token you configure in GitLab's webhook settings is sent verbatim in the x-gitlab-token header. The SDK compares the header value against your secret using constant-time comparison.

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

Typeform

Typeform sends a Base64-encoded HMAC-SHA256 signature in the typeform-signature header with a sha256= prefix. The SDK computes the digest over the raw JSON body.

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

Discord

Discord sends x-signature-ed25519 (hex-encoded signature) and x-signature-timestamp. The SDK verifies using crypto.subtle.verify with Ed25519.

const result = await verifySignature(request, {
  provider: "discord",
  publicKey: process.env.DISCORD_PUBLIC_KEY!,
});

Standard Webhooks

Standard Webhooks is used by Polar, Svix, Resend, Liveblocks, and Novu. It sends three headers: webhook-id, webhook-timestamp, and webhook-signature. The signed payload is {messageId}.{timestamp}.{body}, hashed with HMAC-SHA256 and base64-encoded. Clerk also uses Standard Webhooks signing but has its own dedicated verifyClerkSignature function and "clerk" provider name.

Secrets can include the whsec_ prefix (base64-encoded key after the prefix) or be passed as raw base64.

verifyStandardWebhookSignature(body, headers, secret) takes the headers as a Fetch Headers, a plain object such as Node's req.headers, or name and value pairs. It checks the signature only; check webhook-timestamp yourself if you need replay protection.

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

Meta (WhatsApp / Messenger / Instagram)

Meta signs the raw body with HMAC-SHA256 and sends sha256=hash 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 (the SDK auto-detects Meta by body shape).

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

Lemon Squeezy, Coinbase Commerce, Razorpay, Cal.com

These four 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).

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

Intercom

Intercom signs the raw body with HMAC-SHA1 and sends sha1=hash 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

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 compares it against your secret using constant-time comparison.

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

Square

Square computes a base64 HMAC-SHA256 over {url}{body} and sends it in x-square-hmacsha256-signature.

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

HubSpot

HubSpot computes a base64 HMAC-SHA256 over {method}{url}{body}{timestamp} (the timestamp, in milliseconds, is sent in x-hubspot-request-timestamp) and signs it in x-hubspot-signature-v3. method defaults to "POST" when omitted.

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

Mailgun

Mailgun has no signature header. It embeds signature.{timestamp,token,signature} in the request body and signs {timestamp}{token} with HMAC-SHA256 (hex). The SDK reads the body directly and returns false (never throws) on malformed or non-JSON input.

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

Calendly and Mux

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

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

Bitbucket signs the raw body with HMAC-SHA256 and sends sha256=hash in the x-hub-signature header, the same scheme as GitHub. The SDK distinguishes it from Intercom (which uses x-hub-signature with sha1=) by Bitbucket's unique x-event-key header during auto-detection.

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

DocuSign

DocuSign Connect signs the raw body with HMAC-SHA256 and sends the Base64 result in x-docusign-signature-1.

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

Adyen

Adyen standard notifications store the signature in notificationItems[].NotificationRequestItem.additionalData.hmacSignature. The SDK verifies every notification item in the batch using the hex HMAC key from your Adyen Customer Area. The batch only counts as valid when each item carries its own correct signature.

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

PayPal

PayPal signs transmissionId|transmissionTime|webhookId|crc32(rawBody) with RSA-SHA256. The SDK fetches and caches the certificate URL from paypal-cert-url, only allows PayPal certificate hosts, and uses the configured webhook ID as the verification credential.

If the certificate cannot be downloaded, verifyPayPalSignature throws instead of returning false, because a transport failure is not a signature verdict. Browsers usually block the cross-origin certificate download, so verify PayPal server-side or pass a custom fetchCertificate function.

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

Resend

Resend delivers through Svix, so the scheme is the same as Clerk's: svix-signature holds space-separated v1,<base64> entries, each an HMAC-SHA256 of {svix-id}.{svix-timestamp}.{body} keyed with the base64-decoded whsec_ secret. Resend signs with both the old and the new secret for 24 hours after a rotation, and any matching entry passes.

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

WorkOS

WorkOS sends workos-signature: t=<milliseconds>, v1=<hex>, the hex HMAC-SHA256 of {t}.{body}. Unlike Svix, the key is the signing secret string exactly as WorkOS shows it, prefix included. Like the other t=,v1= providers, the SDK does not enforce a timestamp tolerance, so captured requests can be verified later; check the age of t in your own handler if you need replay protection.

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

Plaid

Plaid templates and detection are supported, but signature verification is not available yet. Real Plaid verification requires fetching a Plaid JWT verification key with Plaid API credentials, then comparing the JWT request_body_sha256 claim to the raw request body.

Generic verifier

verifySignature accepts a captured request and dispatches to the correct provider-specific function. It returns { valid: boolean }.

import { verifySignature } from "@webhooks-cc/sdk";
 
const result = await verifySignature(request, {
  provider: "stripe",
  secret: process.env.STRIPE_WEBHOOK_SECRET!,
});
 
if (result.valid) {
  // Signature verified: safe to process
}

The options type is a discriminated union:

// HMAC/token-based providers
{
  provider: "stripe" | "github" | "shopify" | "twilio" | "slack" | "paddle" | "linear" | "clerk" | "vercel" | "gitlab" | "typeform" | "standard-webhooks" | "meta" | "lemonsqueezy" | "coinbase-commerce" | "razorpay" | "cal" | "intercom" | "telegram" | "square" | "hubspot" | "mailgun" | "calendly" | "mux" | "sentry" | "bitbucket" | "docusign" | "adyen" | "paypal" | "resend" | "workos";
  secret: string;
  url?: string;    // Required for twilio, square, and hubspot
  method?: string; // Used by hubspot (defaults to "POST")
}
 
// Ed25519-based provider (discord)
{
  provider: "discord";
  publicKey: string;
}

Using with captured requests

Verify a request captured by webhooks.cc. Headers and body are preserved exactly as received, so signatures remain valid.

const request = await client.requests.get(requestId);
 
const result = await verifySignature(request, {
  provider: "stripe",
  secret: process.env.STRIPE_WEBHOOK_SECRET!,
});
 
console.log(result.valid); // true

If you are not sure which provider sent the request, detect it first and then pass the matching secret:

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!,
  });
 
  console.log(info.event, result.valid);
}

You can also use provider-specific functions directly. These accept the raw body, signature header, and secret as separate arguments:

import { verifyStripeSignature } from "@webhooks-cc/sdk";
 
const request = await client.requests.get(requestId);
const valid = await verifyStripeSignature(
  request.body,
  request.headers["stripe-signature"],
  process.env.STRIPE_WEBHOOK_SECRET!
);

Forwarded requests

Forwarding sends an HTTP request on in one of two ways, and each has a verifier.

As received (the default for a server URL): the request arrives with its own method, headers and body, so the sender's signature (Stripe, GitHub, ...) still verifies with the sender's secret. To also check that the copy came through your endpoint, verify the webhooks-cc-signature header with verifyRelayedRequest. Pass the exact body bytes:

import { verifyRelayedRequest, WebhookVerificationError } from "@webhooks-cc/sdk";
 
export async function POST(request: Request) {
  const body = new Uint8Array(await request.arrayBuffer());
  try {
    const relay = await verifyRelayedRequest(body, request.headers, process.env.FORWARD_SECRET!);
    console.log(relay.requestId, relay.receivedAt, relay.attempt);
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(null, { status: 401 });
    throw error;
  }
  // ...then verify the provider's own signature and handle the event
  return new Response(null, { status: 204 });
}

It returns { requestId, receivedAt, endpoint, attempt } and throws WebhookVerificationError with code missing_headers or invalid_signature. There is no freshness window: a retry a day later still carries the original receivedAt. Remember requestId to ignore repeats.

Signed JSON (when the endpoint's format is Signed JSON): the request arrives inside a request.received envelope with Standard Webhooks headers. verifyForwardedRequest makes the same checks as verifyForwardedEmail below and returns the event typed as a RequestReceivedEvent:

import { verifyForwardedRequest } from "@webhooks-cc/sdk";
 
const event = await verifyForwardedRequest(
  await request.text(),
  request.headers,
  process.env.FORWARD_SECRET!
);
console.log(event.data.method, event.data.path, event.data.body);

Forwarded emails

Forwarding posts each email an endpoint captures to your server as email.received JSON, signed with Standard Webhooks headers. verifyForwardedEmail checks a delivery and returns it typed as an EmailReceivedEvent. It accepts the request only when:

1. webhook-id, webhook-timestamp and webhook-signature are all present.
2. webhook-timestamp is within five minutes of your clock.
3. One of the signatures in webhook-signature matches the raw body and your endpoint's whsec_ secret, compared in constant time.
4. The body is an email.received event.

import { verifyForwardedEmail, WebhookVerificationError } from "@webhooks-cc/sdk";
 
// A Next.js route handler; the same code runs on Bun, Deno, Hono and Workers
export async function POST(request: Request) {
  try {
    const event = await verifyForwardedEmail(
      await request.text(),
      request.headers,
      process.env.FORWARD_SECRET!
    );
    console.log(event.data.from?.address, event.data.subject, event.data.codes);
    return new Response(null, { status: 204 });
  } catch (error) {
    if (error instanceof WebhookVerificationError) {
      const status = error.code === "invalid_payload" ? 400 : 401;
      return new Response(error.message, { status });
    }
    throw error;
  }
}

In Express, read the body raw, so the bytes you check are the bytes that were signed. req.headers can be passed as it is:

import express from "express";
import { verifyForwardedEmail, WebhookVerificationError } from "@webhooks-cc/sdk";
 
const app = express();
 
app.post("/hooks/email", express.raw({ type: "application/json" }), async (req, res, next) => {
  try {
    const event = await verifyForwardedEmail(req.body, req.headers, process.env.FORWARD_SECRET!);
    await handleInboundEmail(event.data); // your code
    res.sendStatus(204);
  } catch (error) {
    if (error instanceof WebhookVerificationError) {
      res.status(error.code === "invalid_payload" ? 400 : 401).send(error.message);
      return;
    }
    next(error);
  }
});

verifyForwardedEmail(
  body: string | Uint8Array | ArrayBuffer,
  headers: HeadersInput,
  secret: string,
  options?: VerifyForwardedEmailOptions
): Promise<EmailReceivedEvent>

When a check fails it throws WebhookVerificationError, whose code says which:

Every copy of one email has the same webhook-id, so a handler that stores it can skip repeats. To post a captured email to a handler on your machine, see Test your handler locally.

FAQ

Learn more