Core Concepts

Endpoints

A webhook endpoint is a unique URL that captures incoming HTTP requests. Each endpoint has a slug (short identifier) and a URL in the format:

https://go.webhooks.cc/w/{slug}

Endpoints can be permanent or ephemeral. Permanent endpoints (the default for logged-in users) never expire -- they persist until you explicitly delete them, whether you are on the Free or Pro plan. Ephemeral endpoints auto-delete after 12 hours. Create endpoints from the dashboard, CLI, SDK, or MCP server.

// SDK
const endpoint = await client.endpoints.create({ name: "stripe-prod" });

# CLI
whk create stripe-prod

Slugs

The slug is the short, unique identifier in each endpoint URL. It is auto-generated when you create an endpoint and guaranteed unique across the platform. You use slugs to reference endpoints everywhere:

# CLI — listen to incoming requests
whk listen abc123
 
# CLI — forward to localhost
whk tunnel 3000 --endpoint abc123

// SDK — fetch endpoint details
const endpoint = await client.endpoints.get("abc123");

Request capture

When a webhook hits your endpoint URL, the Rust receiver captures the full HTTP request in under 1ms. Every detail is preserved: method, path, headers, body, query parameters, source IP, and timestamp.

Captured requests appear in the dashboard in real-time. No polling, no refresh needed. You can also retrieve them programmatically:

const requests = await client.requests.list(endpoint.slug);

Mock responses

By default, endpoints return 200 OK with an empty body. Configure a mock response to control what the sender sees — status code (100-599), response headers, and body content.

This is useful when the sending service expects a specific response. For example, Stripe retries delivery if it does not receive a 2xx status code.

await client.endpoints.update(endpoint.slug, {
  mockResponse: {
    statusCode: 200,
    headers: { "Content-Type": "application/json" },
    body: '{"received": true}',
  },
});

You can also set mock responses from the dashboard (gear icon), CLI (whk update), or MCP server.

Notification webhooks

Add a notification URL to any endpoint and the receiver will POST a JSON summary (slug, method, path, timestamp, body preview) after each captured request. Works with Slack, Discord, Microsoft Teams, or any service that accepts HTTP POST.

Configure from the dashboard settings dialog, the SDK, or the MCP server. See the notification webhooks guide for setup details.

Ephemeral endpoints

Ephemeral endpoints are temporary — they auto-delete after 12 hours along with all their captured requests. They are created when you use webhooks.cc without logging in, or explicitly via the SDK:

const endpoint = await client.endpoints.create({
  name: "quick-test",
  ephemeral: true,
});

Guest users (no account) can create up to 25 ephemeral endpoints per 12-hour window. No cleanup needed — expired endpoints and their requests are removed automatically.

Tunneling

Tunneling forwards captured webhooks to your local development server. The CLI creates an outbound SSE connection from your machine — no port forwarding, firewall changes, or public IP required.

whk tunnel 3000

This creates an endpoint, prints its URL, and forwards every incoming request to localhost:3000. Path preservation is built in: a request to /w/{slug}/api/webhooks forwards to localhost:3000/api/webhooks.

# Forward an existing endpoint
whk tunnel 3000 --endpoint abc123
 
# Delete the endpoint when the tunnel exits
whk tunnel 3000 -e

Provider templates

Provider templates are pre-built webhook payloads for common services. Each template includes realistic data and proper cryptographic signatures so your handler can verify them.

Supported providers: Stripe, GitHub, Shopify, Twilio, Slack, Paddle, Linear, SendGrid, Clerk, Discord, Vercel, GitLab, and Standard Webhooks (Polar, Svix, Resend).

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

Send templates from the dashboard (Send button), SDK, or MCP server.

Signature verification

Most webhook providers sign payloads with HMAC-SHA256 so you can verify the request came from them and was not tampered with in transit. The SDK includes detection helpers for common providers:

import { isStripeWebhook, isGitHubWebhook, isStandardWebhook } from "@webhooks-cc/sdk";
 
if (isStripeWebhook(request)) {
  // Verify with your Stripe signing secret
}

Verification requires the provider's signing secret, which you configure in your application. The SDK supports signature verification for Stripe, GitHub, Shopify, Twilio, Slack, Paddle, Linear, Clerk, Discord (Ed25519), Vercel, GitLab, and Standard Webhooks.

Quotas

Quotas limit how many webhook requests your endpoints can capture within a billing period. Limits vary by plan:

Quotas are enforced at the receiver level atomically, ensuring accuracy even under high concurrency. When your quota is exhausted, the receiver returns 429 Too Many Requests to the sender.

API keys

API keys authenticate requests from the SDK, CLI, and MCP server. Keys are prefixed with whcc_ and stored as SHA-256 hashes — the raw key is shown only once at creation time.

Generate a key from your account page. Set it as an environment variable:

export WHK_API_KEY="whcc_your_key_here"

const client = new WebhooksCC({
  apiKey: process.env.WHK_API_KEY,
});

Keys have a maximum TTL of 1 year. You can revoke a key at any time from the account page.

Next steps