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 Oct 2026

Install

npm install @webhooks-cc/sdk

See all installation options.

Authentication

Generate an API key from your API keys 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, Discord, DocuSign, Adyen, PayPal, and Plaid 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, with no webhooks.cc infrastructure involved. 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);

Wait for an email

Every endpoint on an account also receives email at <slug>@mailhooks.cc. Add a tag per test run so the test finds its own email, then pull the one-time code out of it:

import { extractCode } from "@webhooks-cc/sdk";
 
const runId = `signup-${Date.now()}`;
const address = client.emails.address(endpoint.slug, runId);
// <slug>[email protected]: use it in your signup form
 
const email = await client.emails.waitFor(endpoint.slug, { tag: runId });
 
console.log(email.email.subject, extractCode(email)); // "Confirm your email", "482913"

waitFor polls for up to 60 seconds by default. To try it without your app, client.emails.sendTest(endpoint.slug, { tag: runId }) delivers a sample email with a six-digit code. See Emails for listing and filtering emails, and forwarding to post them to your server.

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: the 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 and Adyen. 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.