API Reference

import { WebhooksCC } from "@webhooks-cc/sdk";
 
const client = new WebhooksCC({
  apiKey: string,        // Required. Your API key.
  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.
});

import {
  matchMethod,
  matchHeader,
  matchPath,
  matchQueryParam,
  matchBodyPath,
  matchBodySubset,
  matchContentType,
  matchJsonField,
  matchAll,
  matchAny,
} 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"));

import {
  isStripeWebhook, // stripe-signature
  isGitHubWebhook, // x-github-event
  isShopifyWebhook, // x-shopify-hmac-sha256
  isSlackWebhook, // x-slack-signature
  isTwilioWebhook, // x-twilio-signature
  isPaddleWebhook, // paddle-signature
  isLinearWebhook, // linear-signature
  isSendGridWebhook, // user-agent: SendGrid + JSON array body
  isClerkWebhook, // webhook-id + webhook-timestamp + svix-id
  isDiscordWebhook, // x-signature-ed25519 + x-signature-timestamp
  isVercelWebhook, // x-vercel-signature
  isGitLabWebhook, // x-gitlab-event or x-gitlab-token
  isStandardWebhook, // webhook-id + webhook-timestamp + webhook-signature
} from "@webhooks-cc/sdk";

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,
  verifySlackSignature,
  verifyTwilioSignature,
  verifyPaddleSignature,
  verifyLinearSignature,
  verifyClerkSignature,
  verifyDiscordSignature,
  verifyVercelSignature,
  verifyGitLabSignature,
  verifyStandardWebhookSignature,
} 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);

interface Endpoint {
  id: string;
  slug: string;
  name?: string;
  url?: string;
  isEphemeral?: boolean;
  expiresAt?: number;
  createdAt: number;
}
 
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;
}
 
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"
  | "standard-webhooks";
 
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
} from "@webhooks-cc/sdk";