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). Each carries favorite, whether you marked it as a favourite.

get_endpoint

Get details for an endpoint by slug, including favorite, whether you marked it as a favourite.

favorite_endpoint

Mark an endpoint as one of your favourites, or unmark it. A favourite is your own choice, never the endpoint's, so endpoints shared with you through a team can be marked too. Idempotent; returns { slug, favorite }.

update_endpoint

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

preview_layouts

A dry run of the endpoint's layouts on a captured email: which layout matches, the fields and line items it finds, and what earlier parses of its attachments held. Nothing is saved and no pages are used. Pass layouts to try them before saving them with update_endpoint.

Returns any problems with the layouts tried, the plan's layoutsCap, the request it ran on and parsed: the status (matched or no_layout), the layout, fields, lineItems with lineItemColumns, attachments and pages. Long results keep the first 20 line items and leave out sheet rows and attachment text.

preview_response

A dry run of the endpoint's responses: which response rule answers a captured request, and the response with its {{ placeholders }} filled in, exactly as the receiver would send it. Nothing is sent. Pass mockResponse or responseRules to try settings before saving them with update_endpoint.

Returns the rule that answered (rule.index, from 0, or null for the default response), the response (status, headers, body, delay; null means the plain 200 OK), any unknownPlaceholders, and the request it ran against.

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. Takes the filters of search_requests, without its paging and order.

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.

render_email

A captured email in the shape an inbound mail service posts it, to test the handler you wrote for that service against real mail (In a mail provider's shape). Returns { format, method, headers, body }; with targetUrl (your local handler), posts it there and returns the status and the start of the answer.

Forwarding

Forwarding sends what an endpoint captures to up to 10 destinations (servers, Slack or Discord channels, tools such as Zapier or n8n), each with its own kinds, conditions, format, timing and signing secret, queued, retried and logged. Only the endpoint's owner can manage it.

A typical agent session: add_destination, preview_destination to see the exact request it would send, test_forwarding with the destination's id to send one, then list_deliveries to watch it.

list_destinations

List the endpoint's destinations with every setting (header values masked) and, by default, each one's last 24 hours.

add_destination

Add a destination; it is on at once unless enabled: false, and gets a signing secret of its own. Returns the destination with its id.

A filter condition takes field, op and value like a response rule condition, plus kind, email (name: subject, from, to, text or tag), email_field (name: one of the endpoint's named fields), spam_score, email_auth (name: spf, dkim or dmarc) and signature (verified, failed or missing).

update_destination

Change a destination; only the fields passed change. Takes slug, destinationId and any field of add_destination, url included. Switching it off or taking a kind away fails the deliveries still waiting for it.

remove_destination

Remove a destination. Deliveries still waiting for it are marked failed; its log stays.

preview_destination

A dry run: whether the destination's filter lets a captured request through (filterPasses), and the exact request it would send (delivery: method, URL, headers, body, with placeholders filled in and unknownPlaceholders listed). Nothing is sent. Pass destinationId, destination (unsaved fields, on top of the saved ones or with a url on their own), or both.

configure_forwarding

Change the endpoint's primary destination, the one its forwardUrl stands for; only the arguments passed change. Saving the first URL creates it with its signing secret, so the agent can send a test delivery before turning it on. Returns the primary destination's settings, with header values masked. For filters, templates, throttling, delays or more than one destination, use add_destination and update_destination.

get_forwarding_secret

Read the whsec_ secret a destination signs its deliveries 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, or requestId) to a destination 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 whether the destination is on or off and whatever its filter says; nothing is retried or logged.

list_deliveries

With endpointSlug, return the endpoint's delivery log with its counts: { summary, deliveries, nextCursor }. Each row names its destination, and carries 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, to every destination that takes it, or with destinationId to that one whatever its filter says), or every request whose latest delivery failed (endpointSlug, optionally only destinationId, oldest first, up to 1,000 at a time per destination). Pass exactly one of requestId and endpointSlug.

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.

generate_payload_schema

Generate TypeScript interfaces, Zod schemas, Pydantic models, or JSON Schema from the bodies of captured requests. It reads the latest requests (or exactly the ones you name), keeps those that match the filters, and learns one schema from all of their JSON or form bodies: a field missing from some samples is optional, a field that is sometimes null is nullable, and identical nested objects become one type. Filter to one event for the tightest types; the result warns when the samples mix events.

Returns format, name, samples (requests used), skipped (emails and bodies that are neither JSON nor form data), the detected events, and code. The same generator is generateRequestSchema() in @webhooks-cc/sdk, and the dashboard shows it as the Schema view of a request 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, and without a saved connection to a human's account (see the agent credential file), registers these eleven tools instead of the ones above. The eight 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 made in this session, its endpoints move into the account with what they captured; with one from an earlier session, or none, the agent registers for that human directly (endpoints in the answer says which). 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 is saved in the agent credential file, so later sessions start with the full tools; when the human disconnects the agent under Account, Connected agents, the sandbox tools come back.

about_sandbox

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