Skip to content

SDK

The TypeScript SDK lets you create endpoints, capture and replay requests, stream webhooks in real-time, and integrate webhooks.cc into your test suite programmatically.

Updated Mar 2026

Install

npm install @webhooks-cc/sdk

See all installation options.

Authentication

Generate an API key from your account page. Pass it when creating the client:

import { WebhooksCC } from "@webhooks-cc/sdk";
 
const client = new WebhooksCC({
  apiKey: process.env.WHK_API_KEY,
});

Create an endpoint

const endpoint = await client.endpoints.create({
  name: "test-payments",
});
 
console.log(endpoint.url);
// https://go.webhooks.cc/w/<slug>

Send a test webhook

await client.endpoints.send(endpoint.slug, {
  method: "POST",
  headers: { "x-event-type": "payment.success" },
  body: { amount: 4999, currency: "usd" },
});

Send provider templates with signatures

await client.endpoints.sendTemplate(endpoint.slug, {
  provider: "stripe",
  template: "checkout.session.completed",
  secret: "whsec_test_123",
});

Supports Standard Webhooks (Polar.sh, Svix, Clerk, Resend) alongside Stripe, GitHub, Shopify, and Twilio:

await client.endpoints.sendTemplate(endpoint.slug, {
  provider: "standard-webhooks",
  secret: process.env.POLAR_WEBHOOK_SECRET!,
  body: { type: "subscription.created", data: { id: "sub_123" } },
});

Send signed webhooks to localhost

Use sendTo to send properly signed webhooks directly to any URL — no webhooks.cc infrastructure required. Ideal for local integration testing.

const res = await client.sendTo("http://localhost:3000/api/webhooks/polar", {
  provider: "standard-webhooks",
  secret: process.env.POLAR_WEBHOOK_SECRET!,
  body: {
    type: "subscription.created",
    data: { id: "sub_123", status: "active" },
  },
});
 
console.log(res.status); // 200

Wait for a request

Timeouts accept human-readable strings like "30s", "5m", or milliseconds.

import { matchMethod, matchBodyPath } from "@webhooks-cc/sdk";
 
const request = await client.requests.waitFor(endpoint.slug, {
  timeout: "10s",
  match: matchBodyPath("event", "payment.success"),
});
 
console.log(request.body);

Stream requests in real-time

for await (const request of client.requests.subscribe(endpoint.slug)) {
  console.log(request.method, request.path);
  if (request.method === "POST") break;
}

Replay a captured request

const response = await client.requests.replay(request.id, "http://localhost:3000/webhooks");
 
console.log(response.status); // 200

Lifecycle hooks

Use hooks for debugging, logging, or telemetry integration:

const client = new WebhooksCC({
  apiKey: process.env.WHK_API_KEY!,
  hooks: {
    onRequest: ({ method, url }) => console.log(`→ ${method} ${url}`),
    onResponse: ({ status, durationMs }) => console.log(`← ${status} (${durationMs}ms)`),
    onError: ({ error }) => console.error(`✗ ${error.message}`),
  },
});

Error handling in tests

When testing webhook handlers, include the response body in your assertion message for better failure diagnostics:

// Basic — failure message is just "expected 200, received 500"
expect(res.status).toBe(200);
 
// Better — shows the server's error in test output
const text = await res.text();
expect(res.status, `Server responded: ${text}`).toBe(200);

Detect webhook providers

import {
  isStripeWebhook,
  isGitHubWebhook,
  isShopifyWebhook,
  isSlackWebhook,
  isStandardWebhook,
} from "@webhooks-cc/sdk";
 
if (isStandardWebhook(request)) {
  console.log("Standard Webhooks request (Polar, Svix, Clerk, Resend)");
}
 
if (isStripeWebhook(request)) {
  console.log("Stripe webhook received");
}

Learn more

API Reference

All methods, matchers, and types.

Testing patterns

CI/CD integration examples.

MCP Server

AI agent integration for Claude, Cursor, VS Code.