API Reference

import { WebhooksCC } from "@webhooks-cc/sdk";
 
const client = new WebhooksCC({
  apiKey: string,        // Your API key. Required unless getAccessToken is given.
  getAccessToken?: (o?: { forceRefresh?: boolean }) => Promise<string>,
                         // Optional. Supplies an expiring token instead (agents).
  baseUrl?: string,      // Optional. Override API base URL.
  webhookUrl?: string,   // Optional. Override webhook receiver URL.
  timeout?: number,      // Optional. Request timeout in ms (default: 30000).
  retry?: RetryOptions,  // Optional. Automatic retry configuration.
  hooks?: ClientHooks,   // Optional. Lifecycle hooks for observability.
  emailDomain?: string,  // Optional. Domain for emails.address() (default: mailhooks.cc).
});

import { extractCode } from "@webhooks-cc/sdk";
 
const runId = `signup-${Date.now()}`;
await signUp(client.emails.address(slug, runId)); // your app sends the email
 
const email = await client.emails.waitFor(slug, { tag: runId });
const code = extractCode(email); // "482913"

import { extractCode, extractLink, extractFromEmail } from "@webhooks-cc/sdk";
 
extractCode(email); // "482913", or null
extractLink(email); // the confirm, verify, reset or sign-in link, else the first link worth keeping
extractLink(email, { actionOnly: true }); // only an action link, or null
extractFromEmail(email.email); // { codes: string[], links: { url, label, action }[] }

import { emailAddress, extractCode, type EmailReceivedEvent } from "@webhooks-cc/sdk/email";
 
emailAddress("my-app", "run-42"); // "[email protected]"

await client.forwarding.configure(slug, {
  url: "https://api.example.com/hooks",
  http: true,
  headers: [{ name: "Authorization", value: `Bearer ${process.env.HOOK_TOKEN}` }],
  sentField: "publishedAt",
});
const secret = await client.forwarding.secret(slug); // put it in your handler
 
const result = await client.forwarding.test(slug, { kind: "http" });
if (result.delivered) {
  await client.forwarding.configure(slug, { enabled: true });
}

import {
  matchMethod,
  matchHeader,
  matchPath,
  matchQueryParam,
  matchBodyPath,
  matchBodySubset,
  matchContentType,
  matchJsonField,
  matchAll,
  matchAny,
  matchEmail,
  isEmailRequest,
} from "@webhooks-cc/sdk";
 
matchMethod("POST"); // match by HTTP method
matchHeader("x-github-event"); // match header presence
matchHeader("x-github-event", "push"); // match header value
matchPath("/webhooks/**"); // match path with glob wildcards
matchQueryParam("token"); // match query param presence
matchQueryParam("token", "abc"); // match query param value
matchBodyPath("data.object.id", "obj_123"); // match nested JSON path
matchBodySubset({ type: "checkout" }); // match deep partial subset
matchContentType("application/json"); // match content-type ignoring charset
matchJsonField("type", "checkout"); // match top-level JSON field
matchAll(matchMethod("POST"), matchHeader("stripe-signature"));
matchAny(matchMethod("GET"), matchMethod("POST"));
matchEmail({ tag: "run-42", subject: "Confirm" }); // match captured emails (see Emails)
isEmailRequest(request); // true for a captured email with its parsed message

import { detectWebhookInfo, detectWebhookProvider, isTypeformWebhook } from "@webhooks-cc/sdk";
 
const info = detectWebhookInfo(request);
console.log(info?.provider, info?.event);
// "typeform", "form_response"
 
console.log(detectWebhookProvider(request));
// "typeform"
 
if (isTypeformWebhook(request)) {
  // Handle Typeform-specific fields
}

type DetectedWebhookInfo = {
  provider:
    | "stripe"
    | "github"
    | "shopify"
    | "twilio"
    | "slack"
    | "paddle"
    | "linear"
    | "sendgrid"
    | "clerk"
    | "discord"
    | "vercel"
    | "gitlab"
    | "typeform"
    | "standard-webhooks"
    | "meta"
    | "lemonsqueezy"
    | "coinbase-commerce"
    | "razorpay"
    | "cal"
    | "intercom"
    | "telegram"
    | "square"
    | "hubspot"
    | "mailgun"
    | "calendly"
    | "mux"
    | "sentry"
    | "bitbucket"
    | "docusign"
    | "adyen"
    | "paypal"
    | "plaid"
    | "resend"
    | "workos";
  event: string | null;
  via: "header" | "body";
  matchedOn?: string;
};

import { parseJsonBody, parseFormBody, parseBody, extractJsonField } from "@webhooks-cc/sdk";
 
// Parse JSON body safely (returns undefined on failure)
const json = parseJsonBody(request);
 
// Parse form-encoded body
const form = parseFormBody(request);
 
// Auto-detect and parse by content-type
const parsed = parseBody(request);
 
// Extract nested JSON field by dot notation
const email = extractJsonField<string>(request, "data.customer.email");

import { diffRequests } from "@webhooks-cc/sdk";
 
const diff = diffRequests(requestA, requestB);
console.log(diff.matches); // boolean
console.log(diff.differences); // { method?, path?, headers?, body? }

import {
  verifySignature,
  verifyStripeSignature,
  verifyGitHubSignature,
  verifyShopifySignature,
  verifyTwilioSignature,
  verifySlackSignature,
  verifyPaddleSignature,
  verifyLinearSignature,
  verifyDiscordSignature,
  verifyClerkSignature,
  verifyVercelSignature,
  verifyGitLabSignature,
  verifyTypeformSignature,
  verifyStandardWebhookSignature,
  verifyMetaSignature,
  verifyLemonSqueezySignature,
  verifyCoinbaseCommerceSignature,
  verifyRazorpaySignature,
  verifyCalSignature,
  verifyIntercomSignature,
  verifyTelegramSignature,
  verifySquareSignature,
  verifyHubSpotSignature,
  verifyMailgunSignature,
  verifyCalendlySignature,
  verifyMuxSignature,
  verifySentrySignature,
  verifyBitbucketSignature,
  verifyResendSignature,
  verifyWorkOSSignature,
  verifyForwardedEmail,
} from "@webhooks-cc/sdk";
 
// Universal verifier (dispatches by provider)
const result = await verifySignature(request, {
  provider: "stripe",
  secret: "whsec_...",
});
console.log(result.valid); // boolean
 
// Provider-specific verifiers
const valid = await verifyStripeSignature(body, signatureHeader, secret);
const valid = await verifyGitHubSignature(body, signatureHeader, secret);

verifyForwardedEmail(
  body: string | Uint8Array | ArrayBuffer,
  headers: HeadersInput,
  secret: string,
  options?: { toleranceSeconds?: number; now?: number } // defaults: 300, Date.now()
): Promise<EmailReceivedEvent>
 
// HeadersInput: a Fetch Headers, a plain object (Node and Express req.headers,
// array values included) or name and value pairs
type HeadersInput =
  | Headers
  | Record<string, string | string[] | undefined>
  | Iterable<readonly [string, string]>;

interface Endpoint {
  id: string;
  slug: string;
  name?: string;
  url?: string;
  isEphemeral?: boolean;
  expiresAt?: number;
  createdAt: number;
  emailAddress?: string | null; // null for guest endpoints, which receive no email
  showEmailExtracts?: boolean;
  forwardEnabled?: boolean;
  forwardUrl?: string | null; // only returned to the owner
  hasForwardSecret?: boolean;
}
 
interface Request {
  id: string;
  endpointId: string;
  method: string;
  path: string;
  headers: Record<string, string>;
  body?: string;
  queryParams: Record<string, string>;
  contentType?: string;
  ip: string;
  size: number;
  receivedAt: number;
  signatureVerified?: boolean | null;
  signatureError?: string | null;
  signingProvider?: string | null;
  kind?: "http" | "email";
  email?: EmailCapture | null; // the parsed message, for a captured email
}
 
// A captured email: method "EMAIL", path is the recipient address, body the raw message
interface EmailRequest extends Request {
  kind: "email";
  email: EmailCapture;
}
 
interface EmailCapture {
  subject: string | null;
  from: EmailAddress[]; // EmailAddress: { name: string | null; address: string | null }
  to: EmailAddress[];
  cc: EmailAddress[];
  replyTo: EmailAddress[];
  sender: EmailAddress[];
  date: string | null;
  messageId: string | null;
  inReplyTo: string[];
  tag: string | null; // the +tag of the address it was sent to
  text: string | null; // up to 256 KB
  html: string | null; // up to 256 KB
  textFromHtml: boolean;
  attachments: {
    filename: string | null;
    contentType: string;
    size: number;
    contentId: string | null;
    inline: boolean;
  }[];
  auth: EmailAuth | null; // SPF, DKIM, DMARC and reverse DNS results
  smtp: EmailSmtp | null; // client IP, HELO, TLS, envelope; smtp.test marks sample emails
  parseError: boolean;
  truncated: {
    raw: boolean;
    text: boolean;
    html: boolean;
    headers: boolean;
    addresses: boolean;
    attachments: boolean;
  };
}
 
interface EmailCriteria {
  tag?: string | null;
  subject?: string | RegExp;
  from?: string | RegExp;
  to?: string | RegExp;
}
 
interface ListEmailsOptions extends EmailCriteria {
  limit?: number; // emails fetched before filtering (default: 50)
  since?: number;
}
 
interface WaitForEmailOptions extends EmailCriteria {
  timeout?: number | string; // default: 60000
  pollInterval?: number | string; // default: 1000
  since?: number; // default: five minutes ago
  match?: (email: EmailRequest) => boolean;
}
 
interface WaitForEmailsOptions extends WaitForEmailOptions {
  count: number;
}
 
interface SendTestEmailResult {
  status: "captured";
  requestId: string | null;
}
 
interface ConfigureForwardingOptions {
  url?: string | null;
  enabled?: boolean;
}
 
interface ForwardingTestResult {
  status: number | null; // null when no answer arrived
  durationMs: number;
  excerpt: string | null; // the start of your server's response body
  error: string | null; // timeout, refused connection, TLS problem
  delivered: boolean; // your server answered 2xx
  sample: boolean; // no email had arrived, so a sample was sent
}
 
interface EmailDelivery {
  id: string;
  requestId: string;
  status: "pending" | "succeeded" | "failed";
  attempts: number;
  createdAt: number;
  finishedAt: number | null;
  nextAttemptAt: number | null;
  lastStatus: number | null;
  lastError: string | null;
  attemptLog: EmailDeliveryAttempt[];
}
 
interface EmailDeliveryAttempt {
  attemptedAt: number;
  status: number | null;
  durationMs: number;
  error: string | null;
  responseExcerpt: string | null;
}
 
interface RecentEmailDelivery {
  id: string;
  requestId: string;
  status: "pending" | "succeeded" | "failed";
  attempts: number;
  createdAt: number;
  lastStatus: number | null;
  lastError: string | null;
  subject: string | null;
}
 
// The body forwarding posts; field by field in /docs/forwarding#the-request
interface EmailReceivedEvent {
  type: "email.received";
  timestamp: string;
  data: EmailReceivedData;
}
 
interface MockResponse {
  status: number; // 100-599
  body: string;
  headers: Record<string, string>;
  delay?: number; // Response delay in ms (0-30000)
}
 
interface UsageInfo {
  used: number;
  limit: number;
  remaining: number;
  plan: "free" | "pro";
  periodEnd: number | null;
}
 
interface PaginatedResult<T> {
  items: T[];
  cursor?: string;
  hasMore: boolean;
}
 
type TemplateProvider =
  | "stripe"
  | "github"
  | "shopify"
  | "twilio"
  | "slack"
  | "paddle"
  | "linear"
  | "sendgrid"
  | "clerk"
  | "discord"
  | "vercel"
  | "gitlab"
  | "typeform"
  | "standard-webhooks"
  | "meta"
  | "lemonsqueezy"
  | "coinbase-commerce"
  | "razorpay"
  | "cal"
  | "intercom"
  | "telegram"
  | "square"
  | "hubspot"
  | "mailgun"
  | "calendly"
  | "mux"
  | "sentry"
  | "bitbucket"
  | "docusign"
  | "adyen"
  | "paypal"
  | "plaid"
  | "resend"
  | "workos";
 
type VerifyProvider = TemplateProvider;

import {
  WebhooksCCError, // Base error (has statusCode)
  UnauthorizedError, // 401: includes link to get API key
  NotFoundError, // 404: suggests using endpoints.list()
  RateLimitError, // 429: includes retryAfter seconds
  TimeoutError, // Request timeout
  WebhookVerificationError, // Thrown by verifyForwardedEmail(); has a code
} from "@webhooks-cc/sdk";