API Reference

Constructor

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).
  hooks?: ClientHooks,   // Optional. Lifecycle hooks for observability.
});

Endpoints

create(options?: CreateEndpointOptions): Promise<Endpoint>

list(): Promise<Endpoint[]>

get(slug: string): Promise<Endpoint>

update(slug: string, options: UpdateEndpointOptions): Promise<Endpoint>

delete(slug: string): Promise<void>

send(slug: string, options?: SendOptions): Promise<Response>

sendTemplate(slug: string, options: SendTemplateOptions): Promise<Response>

Requests

list(endpointSlug: string, options?: ListRequestsOptions): Promise<Request[]>

get(requestId: string): Promise<Request>

waitFor(endpointSlug: string, options?: WaitForOptions): Promise<Request>

subscribe(slug: string, options?: SubscribeOptions): AsyncIterable<Request>

replay(requestId: string, targetUrl: string): Promise<Response>

Introspection

describe(): SDKDescription

Matchers

Composable functions that return (request) => boolean. Use with waitFor or filter logic.

import {
  matchMethod,
  matchHeader,
  matchBodyPath,
  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
matchBodyPath("data.object.id", "obj_123")  // match nested JSON path
matchJsonField("type", "checkout")           // match top-level JSON field
matchAll(matchMethod("POST"), matchHeader("stripe-signature"))
matchAny(matchMethod("GET"), matchMethod("POST"))

Provider Detection

Each helper checks for a provider-specific header (case-insensitive).

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
} from "@webhooks-cc/sdk";

Duration Strings

timeout and pollInterval accept human-readable strings alongside milliseconds.

"500ms"  →    500
"30s"    →  30000
"5m"     → 300000
"1h"     → 3600000
500      →    500    // numbers passed through

Types

interface Endpoint {
  id: string;
  slug: string;
  name?: string;
  url?: string;
  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 UpdateEndpointOptions {
  name?: string;
  mockResponse?: {
    status: number;
    body: string;
    headers: Record<string, string>;
  } | null;
}

interface SendOptions {
  method?: string;
  headers?: Record<string, string>;
  body?: unknown;
}

interface WaitForOptions {
  timeout?: number | string;
  pollInterval?: number | string;
  match?: (request: Request) => boolean;
}

interface CreateEndpointOptions {
  name?: string;
}

interface ListRequestsOptions {
  limit?: number;
  since?: number;
}

interface SubscribeOptions {
  signal?: AbortSignal;
  timeout?: number | string;
}

type TemplateProvider = "stripe" | "github" | "shopify" | "twilio";

interface SendTemplateOptions {
  provider: TemplateProvider;
  template?: string;
  secret: string;
  event?: string;
  method?: string;
  headers?: Record<string, string>;
  body?: unknown;
  timestamp?: number;
}

Error Classes

Errors include actionable recovery hints when the server message is generic.

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";