Skip to content

API Reference: Teams and Sharing

TypeScript SDK reference for teams, sharing localhost with client.shares, the flow builder and sandbox and agent registration.

Updated Nov 2026

Part of the TypeScript SDK API reference. The constructor, endpoints and direct delivery are on the first page.

Teams

A key has exactly the team access of the account it belongs to. Endpoints shared with you already show up in endpoints.list() and work with every request method by slug except requests.clear, which stays with the owner; this namespace manages the teams themselves.

GET/teams

client.teams.list

List the teams you own or belong to, with role, seats, pooled usage, and subscription state.

list(): Promise<Team[]>
// Team: { id, name, role, seats, memberCount, suspended, subscriptionStatus,
//         requestsUsed, requestLimit, periodEnd, cancelAtPeriodEnd, ... }
GET/teams/:teamId/members

client.teams.members

List a team's members and pending invites. Any member may call this.

members(teamId: string): Promise<TeamMembers>
// Returns: { members: TeamMember[], pendingInvites: TeamInvite[] }
POST/teams/:teamId/endpoints

client.teams.share

Share an endpoint you own with a team. Resolves the slug to an endpoint id for you. The team needs an active subscription; the endpoint's requests then draw from the team's pooled quota.

share(teamId: string, slug: string): Promise<void>
DELETE/teams/:teamId/endpoints/:endpointId

client.teams.unshare

Stop sharing an endpoint you own with a team. Works on suspended teams too.

unshare(teamId: string, slug: string): Promise<void>
POST/teams/:teamId/invite

client.teams.invite

Invite an email address to a team you own. Sends an invite email; accepting claims one of the team's paid seats.

invite(teamId: string, email: string): Promise<TeamInvite>
GET/invites

client.teams.invites

Invites waiting for you, and the calls to answer them.

invites.list(): Promise<TeamInvite[]>
invites.accept(inviteId: string): Promise<void>
invites.decline(inviteId: string): Promise<void>

Sharing localhost

Public links to ports on this computer (whk share) and live tunnels (whk tunnel --live). Previews are served at <name>.sharehooks.cc; Free previews get a random name ending in -free and last 2 hours. Everything the dashboard's Shares page does is here, so an agent never needs it.

GET/shares

client.shares.list

Your previews and live tunnels, live ones first, then the latest that ended, with this month's shared data and your plan's limits. Includes teammates' previews under your teams' names and teammates' live tunnels on endpoints you own.

list(options?: { state?: "live" | "ended" }): Promise<TunnelShareList>
// Returns: { shares: TunnelShare[], usage: TunnelUsage, limits: TunnelLimits,
//            names: TunnelNamesSummary, suspended: boolean, hints: string[] }
POST/shares/:id/stop

client.shares.stop

Stop a preview or live tunnel. The CLI running it is told why and exits. stopped is false when it had already ended; edgeReached is false when the edge could not be told at once, and it ends at the next sync (within half a minute).

stop(id: string): Promise<TunnelStopResult>
// Returns: { ok: true, stopped: boolean, edgeReached: boolean }
GET/shares/:id/requests

client.shares.requests

The last visitor requests to a running preview, newest first: no addresses, a number per visitor.

requests(id: string): Promise<TunnelVisits>
// Returns: { available: boolean, requests: TunnelVisit[] }
RUNwhk share

client.shares.start

Share a local port at a public link as this client's account, by running the whk CLI (Node.js only, whk on the PATH). Resolves once the link is live. A client with an API key passes it to whk; a client from WebhooksCC.connected() makes whk use the same agent credential file, so the share belongs to the account the client sees. Any other client throws.

start(options: { port: number; name?: string; password?: string; whkPath?: string;
  tunnelUrl?: string; onRequest?; onNotice?; onEvent?; timeout?: number }): Promise<LiveShare>
 
const preview = await client.shares.start({ port: 3000 });
console.log(preview.url); // https://sample-preview-1234-free.sharehooks.cc
await preview.stop();
RUNwhk share

share

The same, without a client: whk uses the key you pass (handed over as WHK_API_KEY with WHK_AUTH=key), else WHK_API_KEY from your environment, else its own login.

import { share } from "@webhooks-cc/sdk";
 
const preview = await share({
  port: 5173,
  name: "acme-demo", // a name you reserved (Pro and Business)
  password: process.env.PREVIEW_PASSWORD, // sent through the environment, never the command line
  onRequest: ({ method, path, status }) => console.log(method, path, status),
});
// preview: { url, name, expiresAt, notice, password, port, stop(), closed }
const { reason } = await preview.closed; // settles however it ends

stop() closes the CLI's input and waits for it to exit, so it ends cleanly on every platform. When whk is missing, the error says how to install it (whkInstallHint(); WHK_INSTALL_COMMAND on macOS and Linux, WHK_INSTALL_WINDOWS on Windows). A refusal (no free slot, a name that is taken, data used up) rejects with the CLI's own words.

GET/tunnel-names

client.names.list

Your reserved names and your teams', with how many your plan and each team allow. Own names count against your plan; names kept inside a team count against the team (its plan's names per seat times its seats).

list(): Promise<TunnelNameList>
// Returns: { names: TunnelName[], limit, used, plan?, teams?: TunnelTeamNameCount[] }
POST/tunnel-names

client.names.reserve

Reserve a name (Pro and Business). With team (a team id, or a name that matches one of your teams) it belongs to that team and every member may share under it.

reserve(name: string, options?: { team?: string }): Promise<TunnelName>
DELETE/tunnel-names/:name

client.names.release

Release a name you reserved, or as a team's owner one of its names. A preview running under it stops.

release(name: string): Promise<void>
PUT/tunnel-names/:name/password

client.names.setPassword

Put a password (8 to 200 characters) on every preview under the name, a running one included. clearPassword removes it.

setPassword(name: string, password: string): Promise<void>
clearPassword(name: string): Promise<void>

Requests captured while whk tunnel --live ran carry liveResponse: what the local app answered and the sender got. See Requests and the LiveResponse type.

Flow Builder

POST(chained)

client.flow

Create a fluent workflow builder for common webhook capture, verify, and replay workflows.

const result = await client
  .flow()
  .createEndpoint({ name: "test" })
  .send({ body: { event: "test" } })
  .waitForCapture({ timeout: "10s" })
  .verifySignature({ provider: "stripe", secret: "whsec_..." })
  .replayTo("http://localhost:3000/webhooks")
  .cleanup()
  .run();

Sandbox and Agent Registration

AI agents can use webhooks.cc without an API key. WebhooksCC.sandbox() registers through auth.md, solves the proof-of-work challenge (about 3 seconds), and returns a sandbox client: up to 3 endpoints, 25 captured requests each and 100 in all, deleted 24 hours after registration. See AI Agents for the limits and how a human connects an agent.

POST/api/agent/identity

WebhooksCC.sandbox

const sandbox = await WebhooksCC.sandbox({ clientName: "my-agent" });
 
const endpoint = await sandbox.endpoints.create(); // endpoint.url captures webhooks
const request = await sandbox.requests.waitFor(endpoint.slug, { timeout: "60s" });
 
await sandbox.endpoints.list();
await sandbox.requests.list(endpoint.slug, { limit: 10 });
await sandbox.endpoints.delete(endpoint.slug); // frees a slot; the budget is not refunded

Sandbox endpoints only capture: no mock responses, notifications, signature verification, email or forwarding. Refusals throw SandboxError with the server's code: sandbox_endpoint_limit at 3 endpoints, sandbox_full when the shared sandbox is full. The access token renews itself.

POST/api/agent/identity/claim

sandbox.claim / sandbox.waitForClaim

Connects the agent to a human's account. Show them the link and the code together; only someone signed in with that email can complete it.

const { verificationUri, userCode } = await sandbox.claim({ email: "dev@example.com" });
console.log(`Open ${verificationUri}, sign in, and enter ${userCode}`);
 
const client = await sandbox.waitForClaim(); // a WebhooksCC acting for that account
const endpoints = await client.endpoints.list(); // includes the sandbox endpoints

waitForClaim() rejects with AgentAuthError expired_token when the 15-minute code runs out (call claim() again for a new one), or access_denied when the human declines. After the claim the sandbox client stops working; the returned client renews its token from the claimed assertion for 90 days.

GET(credential file)

WebhooksCC.connected / WebhooksCC.connect

The connection is saved in the agent credential file that the MCP server, the CLI and the Python and Go SDKs share (~/.config/whk/agent.json, or WHK_AGENT_FILE), so a later process picks it up. connected() returns a client for the connected account, or null when there is none or the human has disconnected the agent; fromSavedConnection() is the synchronous form that does not check first. connect() connects an agent to a human's account without a sandbox.

const client = (await WebhooksCC.connected()) ?? (await WebhooksCC.sandbox());
 
const pending = await WebhooksCC.connect({ email: "dev@example.com" });
console.log(`Open ${pending.verificationUri}, sign in, and enter ${pending.userCode}`);
const account = await pending.wait();
POST(protocol)

WebhooksCC.agent

The protocol steps one by one, for callers who drive auth.md themselves:

WebhooksCC.agent.discover({ baseUrl? })
WebhooksCC.agent.challenge()                      // a proof-of-work challenge
WebhooksCC.agent.solveChallenge(challenge, { signal? })
WebhooksCC.agent.registerAnonymous({ clientName? })   // challenge + solve + register
WebhooksCC.agent.registerServiceAuth({ email, clientName? }) // no sandbox; a human must connect it
WebhooksCC.agent.exchange({ assertion })          // one-hour access token
WebhooksCC.agent.startClaim({ claimToken, email? })
WebhooksCC.agent.pollClaim({ claimToken })
WebhooksCC.agent.waitForClaim({ claimToken, timeout? })
WebhooksCC.agent.revoke({ token })

The solver refuses challenges above 2^26 hashes, yields to the event loop about every 50 ms, and works in Node and browsers.

WebhooksCC.register.* (auth.md 0.1) is deprecated: anonymous and ID-JAG registration throw AgentRegisterError with code endpoint_moved, and the email flow stops working on November 30, 2026.