WebhookTool HTTP API

WebhookTool gives you a URL that records every HTTP request sent to it, and every DNS lookup of a name under it, and every email sent to an address of its own. Everything the dashboard does is also available over this API, for scripts, test suites and AI agents. The base URL is https://webhooktool.com, and request and response bodies are JSON unless noted.

Quick start

Create an inbox. The response holds its id, its webhook URL in urls.ingest and its secret, which is returned only this once.

curl -s -X POST https://webhooktool.com/api/v1/inboxes

Send it anything.

curl -X POST 'https://whks.dev/<id>/orders?source=test' \
  -H 'Content-Type: application/json' \
  -d '{"hello": "world"}'

Read what arrived.

curl -s -H 'Authorization: Bearer <secret>' https://webhooktool.com/api/v1/inbox/captures

Open https://webhooktool.com/#<secret> in a browser to see the same inbox in the dashboard.

MCP for AI agents

AI agents can use WebhookTool through its MCP server at https://webhooktool.com/mcp. It needs no account or sign-in, because the agent creates its own inboxes and passes each inbox's secret to the tools that read or change it. To let an agent use an inbox you already have, give it the inbox's private link.

Add it to Claude Code.

claude mcp add --transport http webhooktool https://webhooktool.com/mcp

Or to Codex.

codex mcp add webhooktool --url https://webhooktool.com/mcp

In VS Code, add "webhooktool": {"type": "http", "url": "https://webhooktool.com/mcp"} under servers in mcp.json. In Cursor, add "webhooktool": {"url": "https://webhooktool.com/mcp"} under mcpServers in mcp.json. Other agents take it as a remote MCP server with this URL, over Streamable HTTP.

Anyone who knows an inbox's URL can send to it, so the server tells agents to treat captures as data and not to follow instructions in them.

Inboxes and secrets

• An inbox has an id, a UUID that is part of its webhook URL https://whks.dev/<id>. Anyone who knows the webhook URL can send requests to it, but reading them needs the secret. To operate and maintain the service, the operators may also access inbox data, as the privacy page explains.
• The secret, 26 lowercase letters and digits, reads, changes and deletes the inbox. Send it as a bearer token: Authorization: Bearer <secret>. It is returned only when the inbox is created and cannot be recovered. The link https://webhooktool.com/#<secret> opens the inbox in the dashboard, and https://webhooktool.com/#<secret>/<capture-id> opens one capture.
• An inbox and everything in it are deleted retention_seconds after the inbox was created: 1 day unless you choose between 5 minutes and 3 days. expires_at says when. You can change the time later, but not to less than the inbox's current age.
• An inbox keeps its newest capture_limit captures: 50 unless you choose 1 to 100, and at most 10.0 MiB in total. Older captures are deleted to make room.
• How many inboxes you can have at a time is limited. Destroying an inbox makes room right away.
• How many inboxes you can create within 1 day is limited too, and destroyed and expired inboxes count toward it. Once you reach it, you can create the next inbox 1 day after your latest one.

Sending requests

Any method, path, query string, headers and body sent to https://whks.dev/<id> or a path below it are recorded. Bodies are recorded up to 1.0 MiB. Anything beyond that is cut off and the capture is marked "truncated": true.

The inbox answers with the response in its settings, plus an X-Request-Id header holding the capture's id and X-Robots-Tag: noindex, nofollow, which keeps inbox URLs out of search engines. To answer one request with another status, start the path with a status code from 200 to 599, as in https://whks.dev/<id>/404/anything.

Browsers that load the webhook URL themselves, as a page, a frame, a script, an image or the like, get the body as text/plain; charset=utf-8 whatever content_type says, so an inbox can't show visitors a web page, start a download or run as a script. Calls from a page's scripts with fetch() or XMLHttpRequest, and requests from anything that isn't a browser, such as webhook senders and curl, get the response exactly as set.

With cors on, responses allow every origin, and CORS preflight requests (OPTIONS with Origin and Access-Control-Request-Method headers) are answered with 204 and allow the requested method and headers.

Other answers from the webhook URL are plain text.

DNS lookups

Lookups of any name under <id>.1.whks.dev are recorded in the inbox and answered with no records. The inbox's urls.dns holds that pattern. Lookups count toward the same rate limit as requests, and lookups above it are answered but not recorded.

dig hello.<id>.1.whks.dev

A lookup is a capture with "kind": "dns", "method": "DNS" and a dns object. Its remote_ip is the address of the resolver that sent the lookup, usually not that of the system that made it. When the resolver's address lies in a network's published ranges, insights.network names that network, such as google-public-dns for Google Public DNS.

Emails

Emails to any address at <id>.email.whks.dev, such as hello@<id>.email.whks.dev, are recorded in the inbox. The inbox's urls.email holds that pattern. Messages up to 1.0 MiB are recorded, and longer ones are cut off. Mail for an unknown inbox is refused. Emails count toward the same rate limit as requests, and those above it are refused for the time being, so mail servers send them again later.

An email is a capture with "kind": "email", "method": "SMTP" and an email object. Its proto is SMTP, ESMTP, or ESMTPS after STARTTLS, or UTF8SMTP and UTF8SMTPS when the sender used SMTPUTF8, and its remote_ip is the address of the sending mail server. headers lists the message's header fields in the order they came, files its attachments and other parts by the part's index, and body is the raw message, downloaded as message/rfc822. Getting one capture also returns text and html, the message's plain text and HTML, decoded.

Each email is checked with SPF, DKIM and DMARC when it arrives, and email.auth holds the results: whether the sending server may send mail for the envelope sender's domain, whether each DKIM signature verifies, and whether the message passes the DMARC policy of its From address's domain. The checks use the DNS records the sender's domains had then. Only DMARC ties the From address to its domain's owner.

Endpoints

Every endpoint except POST /api/v1/inboxes needs the inbox's secret as a bearer token, and acts on that inbox. Browsers can only call endpoints that change something from WebhookTool's own pages. Such requests from other sites are refused with 403. Scripts and other programs that are not browsers are not affected.

POST /api/v1/inboxes

Creates an inbox and answers 201 Created with the inbox, including its secret. The body is optional and may hold any settings to start with.

curl -s -X POST https://webhooktool.com/api/v1/inboxes \
  -H 'Content-Type: application/json' \
  -d '{"retention_seconds": 86400, "response": {"status": 202, "body": "accepted"}}'

GET /api/v1/inbox

Returns the inbox.

PATCH /api/v1/inbox

Changes any of the inbox's settings and returns the inbox. Fields you leave out keep their values, also inside response.

curl -s -X PATCH https://webhooktool.com/api/v1/inbox \
  -H 'Authorization: Bearer <secret>' \
  -H 'Content-Type: application/json' \
  -d '{"capture_limit": 100, "response": {"cors": true}}'

DELETE /api/v1/inbox

Destroys the inbox, so it and its captures are deleted right away and its secret stops working. Answers 204 No Content.

GET /api/v1/inbox/captures

Lists captures, without their bodies.

{
  "data": [
    {"id": "01a10371-afd5-7ba1-8019-b929b9af644a", "received_at": "2026-10-03T20:31:02.517Z", "kind": "http", "method": "POST", "url": "https://whks.dev/6ba141bf-2c4f-4601-a998-b0b878661de7/orders?source=test", "status": 200}
  ],
  "total": 1,
  "page": 1,
  "per_page": 50,
  "sort": "newest"
}

The captures in data have every field described under Capture except body. A search stops reading bodies after a set amount of data, and its result then has "partial": true.

DELETE /api/v1/inbox/captures

Deletes every capture, or with q only those matching a search. Answers {"deleted": 3, "partial": false}, where partial is true when the search stopped early, as when listing.

GET /api/v1/inbox/captures/{id}

Returns one capture, including its body.

DELETE /api/v1/inbox/captures/{id}

Deletes one capture. Answers 204 No Content.

GET /api/v1/inbox/captures/{id}/body

Downloads the raw body as application/octet-stream, or an email's raw message as message/rfc822 in an .eml file.

GET /api/v1/inbox/captures/{id}/files/{n}

Downloads the uploaded file whose index is n in the capture's files, or an email's part with that index, decoded.

GET /api/v1/inbox/captures/{id}/as/{format}

Returns the request as text that sends it again. format is curl, httpie, fetch (JavaScript), python (requests), powershell, or har for a HAR 1.2 document. The copy is addressed to the inbox's webhook URL with the same path and query, not to the host named in the original request, which the sender chose. Not available for DNS lookups or emails.

PUT /api/v1/inbox/captures/{id}/note

Sets the capture's note, up to 10000 characters, and returns the capture without its body. An empty note removes it.

curl -s -X PUT https://webhooktool.com/api/v1/inbox/captures/<capture-id>/note \
  -H 'Authorization: Bearer <secret>' \
  -H 'Content-Type: application/json' \
  -d '{"note": "retried by the provider"}'

POST /api/v1/inbox/captures/{id}/signature

Checks the signature of an Amazon SNS or PayPal capture with the signing certificate it names. The server downloads that certificate from Amazon's or PayPal's own servers, never from anywhere else, and keeps it for 12 hours. A PayPal signature also needs webhook_id, the ID PayPal gave the webhook. Signatures made with a shared secret, such as GitHub's or Stripe's, are checked in the dashboard instead, which keeps the secret in the browser. So are SendGrid's Signed Event Webhook (sendgrid, ECDSA P-256 over the timestamp and the body) and Discord's interactions (discord, Ed25519 over the timestamp and the body), with the public key SendGrid or Discord shows you. Discord's needs a browser that supports Ed25519 in WebCrypto.

Some senders sign without naming a certificate, and these are checked with keys their issuer publishes.

• Google Pub/Sub push requests (google-oidc) carry a token from Google in Authorization, checked with Google's keys from www.googleapis.com. Its issuer must be accounts.google.com.
• Microsoft Graph change notifications with resource data (microsoft-graph) carry tokens in validationTokens, and Azure Event Grid with Microsoft Entra authentication (azure-entra) carries one in Authorization. Both are checked with Microsoft identity's keys from login.microsoftonline.com, and their issuer must be Microsoft identity for a tenant. Each Graph token must also be issued to Microsoft Graph Change Tracking, the app 0bf30f3b-4a52-48df-9a82-234910c4a086.
• App Store Server Notifications V2 (apple) carry the certificates that signed signedPayload. They must lead to Apple Root CA - G3, which WebhookTool carries, and carry the marks Apple puts on its signing certificates, so nothing is downloaded.

Tokens and certificates must have been valid when the request arrived, allowing 5 minutes of clock difference for tokens. A token shows who sent the request, but doesn't cover its body. The result's token holds what the token says, such as its issuer, subject, audience, the service account's email and whether Google marked it email_verified, the app that requested it, its tenant, issued_at, expires_at, and the key_id and keys_url of the key that checked it. For Apple, certificate is the certificate that signed the payload, and token holds the app bundle ID and the environment.

To check a JWT that decoded lists instead, send its from as layer, as in -d '{"layer": "body.id_token"}'. Only tokens that Google (accounts.google.com), Microsoft identity or Sign in with Apple (https://appleid.apple.com) issued with RS256 can be checked, with keys downloaded only from those issuers' fixed addresses. Any other token gets 400 with not_checkable.

curl -s -X POST https://webhooktool.com/api/v1/inbox/captures/<capture-id>/signature \
  -H 'Authorization: Bearer <secret>'

{"scheme": "aws-sns", "valid": true, "certificate": {"url": "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-<id>.pem", "subject": "CN=sns.amazonaws.com", "issuer": "CN=Amazon RSA 2048 M01,O=Amazon,C=US", "not_after": "2027-06-21T23:59:59Z"}}

For PayPal, send the webhook ID as JSON, as in -H 'Content-Type: application/json' -d '{"webhook_id": "1JE4291016473214C"}'.

{"scheme": "google-oidc", "valid": true, "token": {"issuer": "https://accounts.google.com", "subject": "112233445566778899000", "audience": ["https://example.com/push"], "email": "pusher@my-project.iam.gserviceaccount.com", "email_verified": true, "key_id": "<key-id>", "keys_url": "https://www.googleapis.com/oauth2/v3/certs", "issued_at": "2026-10-12T10:00:00Z", "expires_at": "2026-10-12T11:00:00Z"}}

valid is false with a reason when the signature fails. mismatch means it doesn't match the certificate or key, certificate_url that the certificate it names isn't on the provider's own servers, so the provider didn't send it, certificate_unknown that it is on the provider's own domain but not where WebhookTool expects certificates, so it wasn't checked, certificate_expired that the certificate had expired when the request arrived, certificate_chain that Apple's certificates don't lead to Apple's root or lack Apple's marks, and unsupported that it uses a version that can't be checked. For tokens, token_expired means the token had expired or wasn't valid yet when the request arrived, key_unknown that its issuer doesn't publish the key that signed it, which also happens once an issuer drops an old key, issuer that the sender doesn't issue tokens like it, and token_app that a Microsoft Graph token wasn't issued to Microsoft Graph Change Tracking. A capture without such a signature, or whose body was cut off, gets 400 with not_checkable.

GET /api/v1/inbox/export

Downloads captures with their bodies, oldest first, as a file. format is json (an array of captures, the default), csv (one row per capture, with lists and objects as JSON, and a leading ' on text starting with =, +, - or @ so spreadsheets do not run it as a formula) or har (HAR 1.2, without DNS lookups and emails). With q, only captures matching a search are included.

curl -s -OJ -H 'Authorization: Bearer <secret>' 'https://webhooktool.com/api/v1/inbox/export?format=har'

Objects

Inbox

{
  "id": "6ba141bf-2c4f-4601-a998-b0b878661de7",
  "secret": "k7n2xq4vb6mz3wd5rf2hp7ty4c",
  "urls": {
    "ingest": "https://whks.dev/6ba141bf-2c4f-4601-a998-b0b878661de7",
    "dns": "*.6ba141bf-2c4f-4601-a998-b0b878661de7.1.whks.dev",
    "email": "*@6ba141bf-2c4f-4601-a998-b0b878661de7.email.whks.dev"
  },
  "created_at": "2026-10-03T20:25:36.123456Z",
  "expires_at": "2026-10-04T00:25:36.123456Z",
  "captures": 0,
  "settings": {
    "response": {
      "status": 200,
      "content_type": "text/plain; charset=utf-8",
      "body": "",
      "headers": [],
      "delay_ms": 0,
      "cors": false
    },
    "retention_seconds": 86400,
    "capture_limit": 50,
    "ip_mode": "full"
  }
}

Settings

Capture

{
  "id": "01a10371-afd5-7ba1-8019-b929b9af644a",
  "received_at": "2026-10-03T20:31:02.517Z",
  "kind": "http",
  "method": "POST",
  "url": "https://whks.dev/6ba141bf-2c4f-4601-a998-b0b878661de7/orders?source=test",
  "host": "whks.dev",
  "path": "/orders",
  "query": [{"name": "source", "value": "test"}],
  "headers": [
    {"name": "Accept", "value": "*/*"},
    {"name": "Content-Length", "value": "18"},
    {"name": "Content-Type", "value": "application/json"},
    {"name": "Host", "value": "whks.dev"},
    {"name": "User-Agent", "value": "curl/8.7.1"}
  ],
  "proto": "HTTP/1.1",
  "remote_ip": "203.0.113.7",
  "content_type": "application/json",
  "content_length": 18,
  "body_size": 18,
  "status": 200,
  "body": "{\"hello\": \"world\"}",
  "body_encoding": "utf-8"
}

query, form, form_truncated, files, tls, remote_ip, truncated, note, insights, decoded, dns, email, text and html are left out when they are empty or do not apply.

Search

Use q to search, for example method:post status:4xx -path:/health.

curl -s -G -H 'Authorization: Bearer <secret>' https://webhooktool.com/api/v1/inbox/captures \
  --data-urlencode 'q=method:post status:4xx -path:/health'

Plain words match anywhere in a capture's method, URL, sender address, note, header, query and form names and values, file names, named sender and event, and body. All matching ignores case. Terms are combined with AND. Use OR, NOT or a leading -, parentheses, and double quotes around values with spaces. A search can be up to 1000 characters long with up to 32 terms. It stops reading bodies after a set amount of data and then reports "partial": true.

Errors

Errors from the API have a JSON body with a machine-readable code and a message.

{"error": {"code": "invalid", "message": "capture_limit: must be between 1 and 100"}}

Limits