Matchers & Helpers

import {
  matchMethod,
  matchHeader,
  matchPath,
  matchQueryParam,
  matchBodyPath,
  matchBodySubset,
  matchContentType,
  matchAll,
  matchAny,
} from "@webhooks-cc/sdk";

matchMethod(method: string): (request: Request) => boolean

const req = await client.requests.waitFor(slug, {
  match: matchMethod("POST"),
});

matchHeader(name: string, value?: string): (request: Request) => boolean

// Header exists (any value)
matchHeader("stripe-signature");
 
// Header exists with exact value
matchHeader("x-github-event", "push");

matchPath(pattern: string): (request: Request) => boolean

matchPath("/webhooks/*"); // matches /webhooks/stripe, not /webhooks/stripe/events
matchPath("/webhooks/**"); // matches /webhooks/stripe/events/123
matchPath("/api/*/webhooks"); // matches /api/v1/webhooks

matchQueryParam(key: string, value?: string): (request: Request) => boolean

// Parameter exists (any value)
matchQueryParam("token");
 
// Parameter exists with exact value
matchQueryParam("token", "abc123");

matchBodyPath(path: string, value: unknown): (request: Request) => boolean

matchBodyPath("type", "checkout.session.completed");
matchBodyPath("data.object.id", "obj_123");
matchBodyPath("items.0.name", "Widget");

matchBodySubset(subset: Record<string, unknown>): (request: Request) => boolean

matchBodySubset({
  type: "checkout.session.completed",
  data: { object: { status: "complete" } },
});

matchContentType(type: string): (request: Request) => boolean

matchContentType("application/json");
// matches "application/json; charset=utf-8"

matchAll(...matchers: Array<(request: Request) => boolean>): (request: Request) => boolean

matchAll(matchMethod("POST"), matchHeader("content-type", "application/json"));

matchAny(...matchers: Array<(request: Request) => boolean>): (request: Request) => boolean

matchAny(matchMethod("PUT"), matchMethod("PATCH"));

matchVerified(): (request: Request) => boolean

const req = await client.requests.waitFor(slug, {
  match: matchAll(matchMethod("POST"), matchVerified()),
  timeout: "30s",
});
// req.signatureVerified === true

matchUnverified(): (request: Request) => boolean

const failed = await client.requests.waitFor(slug, {
  match: matchUnverified(),
  timeout: "10s",
});
console.log(failed.signatureError); // structured error JSON

const req = await client.requests.waitFor(slug, {
  timeout: "10s",
  match: matchAll(
    matchMethod("POST"),
    matchHeader("stripe-signature"),
    matchBodyPath("type", "checkout.session.completed")
  ),
});

const req = await client.requests.waitFor(slug, {
  timeout: "30s",
  match: matchAll(
    matchMethod("POST"),
    matchAny(matchBodyPath("type", "invoice.paid"), matchBodyPath("type", "invoice.payment_failed"))
  ),
});

import {
  detectWebhookInfo,
  detectWebhookProvider,
  isStripeWebhook,
  isGitHubWebhook,
  isShopifyWebhook,
  isSlackWebhook,
  isTwilioWebhook,
  isPaddleWebhook,
  isLinearWebhook,
  isSendGridWebhook,
  isClerkWebhook,
  isDiscordWebhook,
  isVercelWebhook,
  isGitLabWebhook,
  isTypeformWebhook,
  isStandardWebhook,
  isMetaWebhook,
  isLemonSqueezyWebhook,
  isCoinbaseCommerceWebhook,
  isRazorpayWebhook,
  isCalWebhook,
  isIntercomWebhook,
  isTelegramWebhook,
  isSquareWebhook,
  isHubSpotWebhook,
  isMailgunWebhook,
  isCalendlyWebhook,
  isMuxWebhook,
  isSentryWebhook,
  isBitbucketWebhook,
} from "@webhooks-cc/sdk";

const info = detectWebhookInfo(request);
 
if (info?.provider === "typeform") {
  console.log(info.event); // "form_response"
}
 
console.log(detectWebhookProvider(request)); // "typeform"

const request = await client.requests.waitFor(slug, { timeout: "10s" });
 
if (isStripeWebhook(request)) {
  // Verify Stripe signature and handle event
} else if (isGitHubWebhook(request)) {
  // Verify GitHub signature and handle event
} else if (isStandardWebhook(request)) {
  // Standard Webhooks request (Polar, Svix, Clerk, Resend)
} else {
  console.log("Unknown provider");
}

import { parseJsonBody, parseFormBody, parseBody, extractJsonField } from "@webhooks-cc/sdk";

parseJsonBody(request: Request): unknown | undefined

const body = parseJsonBody(request);
if (body) {
  console.log(body);
}

parseFormBody(request: Request): Record<string, string | string[]> | undefined

const form = parseFormBody(request);
if (form) {
  console.log(form.email); // "[email protected]"
  console.log(form.tags); // ["a", "b"] if repeated
}

parseBody(request: Request): unknown | Record<string, string | string[]> | string | undefined

const parsed = parseBody(request);

extractJsonField<T>(request: Request, path: string): T | undefined

const email = extractJsonField<string>(request, "data.customer.email");
const firstItem = extractJsonField<string>(request, "items.0.name");

import { matchJsonField } from "@webhooks-cc/sdk";
 
const req = await client.requests.waitFor(slug, {
  match: matchJsonField("type", "checkout.session.completed"),
});