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 May 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 Typeform and Standard Webhooks (Polar.sh, Svix, Clerk, Resend) alongside Stripe, GitHub, Shopify, Twilio, Slack, Paddle, Linear, Clerk, Vercel, GitLab, SendGrid templates, and Discord templates:

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 { detectWebhookInfo } from "@webhooks-cc/sdk";
 
const info = detectWebhookInfo(request);
 
if (info) {
  console.log(info.provider, info.event);
  // "typeform", "form_response"
}

The helper detects providers from headers first, then body shape for providers like SendGrid. Use the boolean helpers (isStripeWebhook, isGitHubWebhook, isTypeformWebhook, etc.) when you only need one branch.

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.