Tool Reference

Endpoint management

create_endpoint

Create a new webhook endpoint. Returns the endpoint slug and full URL.

mockResponse fields:

create_endpoints

Create 1--20 endpoints in a single call. Returns an array of created endpoints.

list_endpoints

List the endpoints you own (each with sharedWith) and those shared with you through a subscribed team (each with fromTeam, the oldest share, and fromTeams, every one of your teams it is shared with).

get_endpoint

Get details for an endpoint by slug.

update_endpoint

Update an endpoint's name, mock response, notification webhook, signing configuration, or whether codes and links are picked out of its emails.

delete_endpoint

Delete an endpoint and all its captured requests.

delete_endpoints

Delete 1--100 endpoints in a single call.

Sending and testing

send_webhook

Send a test webhook to a hosted webhooks.cc endpoint. Supports manual payloads and provider templates, including signed templates for providers that support shared-secret or token-style signing.

Example provider-template call:

{
  "slug": "abc123",
  "provider": "typeform",
  "template": "form_response",
  "secret": "typeform_test_secret"
}

send_to

Send a webhook directly to any URL -- localhost, staging, production. Same signing support as send_webhook.

preview_webhook

Build a webhook request without sending it. Returns the computed URL, method, headers, and body so you can inspect signatures before delivery.

test_webhook_flow

Run a full end-to-end test: create endpoint, set mock response, send webhook, wait for capture, verify signature, replay to target, clean up.

Request management

list_requests

List captured requests for an endpoint, newest first. Emails come back with kind: "email" and the parsed message in email, without the raw message or the HTML part (email.htmlSize gives its length; size is the message size in bytes), and with the text cut at 8,000 characters. An email that is still too big loses its headers (headersOmitted), then sender, address and attachment entries past the first 5, then text, and as a last resort everything but its subject, first sender (fromTotal), tag, date and text (trimmed), so each email fits on its own. The other request tools and the MCP resources return emails the same way; use get_email for the HTML.

get_request

Get full details of a captured request, including headers and body.

wait_for_request

Poll until a request arrives at an endpoint, then return it.

wait_for_requests

Poll until a specified number of requests arrive at an endpoint.

search_requests

Full-text search across captured requests. Supports time ranges, method filters, and pagination.

count_requests

Count requests matching the given filters. Accepts the same filter parameters as search_requests.

clear_requests

Delete captured requests for an endpoint without deleting the endpoint itself.

Emails

Every endpoint on an account receives email at {slug}@mailhooks.cc, and at {slug}+{tag}@mailhooks.cc for any tag, which lands on the same endpoint. Use a fresh tag for each test run so an agent finds its own email. Each email counts as one request. The one-time code and main link come from the same finder as the dashboard; they are left out when the endpoint's owner turned off "Show codes and links found in emails".

list_emails

List the emails an endpoint received, newest first, one line each: id, receivedAt, address, tag, subject, from, code, link, and the number of attachments. A main link over 8,000 characters is left out (linkOmitted).

get_email

Get one email: by requestId, or the newest at endpointSlug (optionally with a tag). Pass exactly one of the two. Returns the parsed message in the shape of forwarded JSON (subject, from, to, text, attachments, auth, headers, ...) with code and link first. The text is cut at 8,000 characters (textTruncated: true), and the HTML is left out (htmlSize gives its length) unless includeHtml is set. Tool output is capped at 32 KB, so a large email is trimmed to fit and stays valid JSON: first its headers are left out (headersOmitted), then codes and links past the first 10 (codesTruncated, linksTruncated), then address and attachment entries past the first 5 (toTotal, attachmentsTotal, ...); then the HTML and the text are cut (htmlTruncated, textTruncated), and as a last resort only the essentials stay (trimmed), without a main link too long to use (linkOmitted).

wait_for_email

Wait for an email to arrive, for example after the agent submitted a signup form, then return it like get_email. Looks back five minutes unless since is given.

send_test_email

Deliver a sample email with a 6-digit code and a link, to try the email tools before wiring up a real sender. It counts as one request and skips SMTP, so no sender checks run on it. Returns status, requestId and the address it went to.

Forwarding

Forwarding sends every HTTP request and email an endpoint captures to a URL or a Slack or Discord channel, queued, retried and logged with its timing. Only the endpoint's owner can manage it.

configure_forwarding

Change the forwarding settings; only the arguments passed change. Saving the first URL creates the signing secret, so the agent can send a test delivery before turning forwarding on. Turning forwarding (or a kind) off fails the deliveries still waiting. Returns every forwarding setting, with header values masked.

get_forwarding_secret

Read the whsec_ secret deliveries are signed with, or replace it with rotate: true. The value is a credential and ends up in the agent's context: have the agent put it in the handler's environment, not in code.

test_forwarding

Send the newest captured request of a kind (or a sample, if none has arrived) to the saved URL once, exactly as a delivery would go out, and report the status, durationMs, the start of the answer (excerpt), error, delivered, the format and target used, and the sender's own timestamp when the request had one. Works with forwarding on or off; nothing is retried or logged.

list_deliveries

With endpointSlug, return the endpoint's delivery log with its counts: { summary, deliveries, nextCursor }. Rows carry senderAt when the request had the sender's own timestamp, so receivedAt - senderAt is the time to reach webhooks.cc. With requestId, return every delivery and try of one request or email. Pass exactly one.

redeliver

Forward again with the current settings: one request or email (requestId, which also sends one that was never forwarded), or every request whose latest delivery failed (endpointSlug, oldest first, up to 1,000 at a time). Pass exactly one. Fails while forwarding is off.

Request analysis

replay_request

Replay a captured request to a target URL. Sends the original method, headers, and body.

compare_requests

Diff two captured requests. Returns structured differences in method, headers, and body.

extract_from_request

Extract specific JSON fields from a captured request body using dot-notation paths.

verify_signature

Verify the webhook signature on a captured request. Supports two modes:

1. Stored result (no provider/secret) — returns the pre-computed server-side verification result when signing is configured on the endpoint
2. Client-side (with provider + secret for HMAC providers, or provider + publicKey for Discord) — performs verification on demand

Teams

An API key carries the team access of the account it belongs to. Shared endpoints already appear in list_endpoints and work with every request tool by slug except clear_requests, which only the owner may call; these tools manage the teams. Invites are not exposed: accepting one claims a paid seat and inviting sends email, so those stay with people (dashboard, whk teams, or the SDK).

list_teams

List the teams you own or belong to: role, seats, requestsUsed and requestLimit of the pooled quota, periodEnd, and whether the team is suspended. No parameters.

list_team_members

List a team's members and pending invites.

share_endpoint

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

unshare_endpoint

Stop sharing an endpoint you own with a team. Same parameters as share_endpoint.

Utilities

get_usage

Your plan's request usage, remaining quota, and period end, plus a teams array with the pooled quota of every subscribed team you belong to. No parameters.

list_provider_templates

List supported webhook providers, available templates, and signing metadata. Use this before send_webhook when an agent needs to pick a realistic provider payload.

Example:

{
  "provider": "typeform"
}

describe

Self-documenting schema of all available operations and their parameters. No parameters.

Without an API key: the agent sandbox

A server started without WHK_API_KEY registers these ten tools instead of the ones above. The seven endpoint and request tools have the same names and arguments as the full tools, but run in the agent sandbox (auth.md): up to 3 endpoints at a time, 25 captured requests each and 100 in all, deleted 24 hours after the sandbox was created. Captures are readable only by this agent.

connect_account

Connect the agent to a human's account. Returns verificationUri, a 6-digit userCode and a tellTheHuman line to show them: they sign in or sign up with that email and enter the code. With a sandbox, its endpoints move into the account with what they captured; without one, the agent registers for that human directly. Calling it again gives a new code.

wait_for_connection

Wait for the human to enter the code. On success the full tools for their account replace the sandbox tools (the server sends notifications/tools/list_changed). Otherwise it returns status waiting (call it again), expired (call connect_account for a new code) or declined. The connection lasts while the server runs; set WHK_API_KEY for a lasting setup.

about_sandbox

The sandbox limits, what needs an account, and how to connect one. No parameters and no network call.