Matchers & Helpers

import {
  matchMethod,
  matchHeader,
  matchPath,
  matchQueryParam,
  matchBodyPath,
  matchBodySubset,
  matchContentType,
  matchAll,
  matchAny,
  matchVerified,
  matchUnverified,
  matchEmail,
  isEmailRequest,
} 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

matchEmail(criteria?: EmailCriteria): (request: Request) => boolean

const request = await client.requests.waitFor(slug, {
  match: matchEmail({ tag: runId, subject: "Confirm your email" }),
});
 
// Composes with the other matchers
matchAll(matchEmail({ from: "[email protected]" }), matchEmail({ subject: /reset/i }));

isEmailRequest(request: Request): request is EmailRequest

const requests = await client.requests.list(slug);
const emails = requests.filter(isEmailRequest);
console.log(emails.map((email) => email.email.subject));

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 { extractCode, extractLink, extractFromEmail, htmlToText } from "@webhooks-cc/sdk";

extractCode(input: Request | EmailCapture): string | null

const email = await client.emails.waitFor(slug, { tag: runId });
const code = extractCode(email); // "482913"

extractLink(input: Request | EmailCapture, options?: { actionOnly?: boolean }): string | null

const link = extractLink(email);
if (link) await page.goto(link);
 
// Only a confirm, verify, reset or sign-in link, or null
const actionLink = extractLink(email, { actionOnly: true });

extractFromEmail(email: Pick<EmailCapture, "subject" | "text" | "html">): EmailExtracts
// EmailExtracts: { codes: string[]; links: { url: string; label: string | null; action: boolean }[] }

const { codes, links } = extractFromEmail(email.email);

htmlToText(html: string): string

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,
  isDocuSignWebhook,
  isAdyenWebhook,
  isPayPalWebhook,
  isPlaidWebhook,
  isResendWebhook,
  isWorkOSWebhook,
} 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"),
});