Test MCP Events Deliveries Locally with the Hookdeck CLI
When you add MCP Events to an MCP server, you need a subscriber to test against: a public https callback URL that answers the verification handshake, and somewhere to read each signed delivery. This guide sets one up with the Hookdeck CLI. You subscribe to your server with a Hookdeck URL, and hookdeck listen forwards each delivery to a receiver on your machine, where you can inspect the headers, check the signature and replay it.
MCP Events is a draft extension, proposed in SEP-3415, and details may change before it's accepted.
How it fits together
- You create an MCP Events source in Hookdeck. It holds the subscription's signing secret, and its URL becomes the callback URL.
- You call
events/subscribeon your MCP server with that URL and secret. - Your server sends a signed verification challenge to the URL. The source checks the signature and the timestamp, then echoes the challenge, so the subscription is created.
- Your server delivers each event to the same URL. The source checks the signature again, stores the request and answers
200. hookdeck listenforwards the delivery, headers and body unchanged, tolocalhost. You read it in the terminal and in your receiver, and replay it as often as you like.
What this tests, and what it doesn't
It tests what your server sends: the handshake, the Standard Webhooks headers and signature, the X-MCP-Subscription-Id header, the event envelope and your argument filters. It also tests your own receiver code, if you're building one.
It doesn't test your server's retries. Hookdeck answers 200 once it has stored a delivery, whatever happens on your machine, so your server never sees a failure. To check your retry schedule and your handling of 410 and 413, use Outpost's mcp-dev check, which runs SEP-3415's webhook rules against an MCP Events server.
Prerequisites
- An MCP server that offers at least one event in webhook mode, running locally or deployed. Your server needs to reach Hookdeck's
httpsURL; it doesn't need to be public itself. - The Hookdeck CLI, installed and logged in (
npm install hookdeck-cli -g, thenhookdeck login). A free Hookdeck account is enough. - Node.js 20 or later for the example receiver.
Step 1: Create the test subscription's source
The subscriber supplies the signing secret. SEP-3415 requires whsec_ followed by base64 that decodes to 24 to 64 bytes:
export SECRET="whsec_$(openssl rand -base64 32)"
Create an MCP Events source that holds the secret, and note its id and url:
hookdeck gateway source create --name mcp-events-test --type MCP_EVENTS \
--webhook-secret "$SECRET" --output json
export SOURCE_URL=<the url from the output>
A source holds one secret, so use one source per test subscription.
Step 2: Start a receiver and the CLI
The receiver prints each delivery's headers and verifies its signature with the standardwebhooks library, the same check a real subscriber makes:
// receiver.mjs
import { createServer } from "node:http";
import { Webhook } from "standardwebhooks";
const webhook = new Webhook(process.env.SECRET);
createServer((req, res) => {
const chunks = [];
req.on("data", (chunk) => chunks.push(chunk));
req.on("end", () => {
const raw = Buffer.concat(chunks).toString("utf8");
const headers = {
"webhook-id": req.headers["webhook-id"] ?? "",
"webhook-timestamp": req.headers["webhook-timestamp"] ?? "",
"webhook-signature": req.headers["webhook-signature"] ?? "",
};
console.log(headers, "subscription:", req.headers["x-mcp-subscription-id"]);
try {
webhook.verify(raw, headers); // checks the signature and the 5-minute window
console.log("signature OK", JSON.parse(raw));
res.writeHead(200).end();
} catch (error) {
console.log("signature FAILED:", error.message);
res.writeHead(400).end();
}
});
}).listen(4000);
Run it with the same SECRET, then start the CLI in a second terminal:
npm install standardwebhooks
node receiver.mjs
# second terminal
hookdeck listen 4000 mcp-events-test
listen finds the MCP Events source and connects it to a new CLI destination, cli-mcp-events-test, with no rules. That suits testing: without the deduplicate rule you'd use in production, you see every request your server sends, duplicates included.
Create the source before you start listen. If no source of that name exists, listen creates a plain one, which can't answer the handshake.
Step 3: Subscribe, and watch the handshake
Call events/subscribe on your server with the source URL and the secret. Any MCP client that supports MCP Events works. With curl against a server on protocol version 2026-07-28:
curl -s http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer $MCP_TOKEN" \
-H "MCP-Protocol-Version: 2026-07-28" \
-H "Mcp-Method: events/subscribe" \
-H "Mcp-Name: order.created" \
-d @- <<EOF
{
"jsonrpc": "2.0", "id": 1, "method": "events/subscribe",
"params": {
"name": "order.created",
"arguments": { "currency": "USD" },
"delivery": { "mode": "webhook", "url": "$SOURCE_URL", "secret": "$SECRET" },
"ttlMs": 3600000,
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": { "name": "curl", "version": "1.0.0" },
"io.modelcontextprotocol/clientCapabilities": {
"extensions": { "io.modelcontextprotocol/events": {} }
}
}
}
}
EOF
Before your server answers, it sends the challenge to the source. If the signature verifies and webhook-timestamp is within 5 minutes, the source echoes the challenge, and curl prints the subscription's id and refreshBefore:
{"result":{"resultType":"complete","id":"sub_1d5fb712e33e66946e2abe96cc677e76","refreshBefore":"2026-11-17T15:03:41Z","cursor":null,"truncated":false,...},"jsonrpc":"2.0","id":1}
The handshake is answered at the source. It doesn't reach your receiver, and a handshake that passes isn't kept in the request log.
If you'd rather use a client than curl, the Outpost demo's test subscriber takes the source URL and secret, and runs its own receiver on port 4000 that verifies each delivery. Stop receiver.mjs first, then run, from a checkout of the demo:
MCP_SERVER_URL=http://localhost:3000/mcp MCP_TOKEN=<token> \
npm run client -- --currency USD --callback-url "$SOURCE_URL" --secret "$SECRET"
If the handshake fails
If the subscribe fails with -32027 (CallbackEndpointError), the source rejected the handshake with 401 and the body {"error":"Invalid signature"}. Outpost, for example, reports it as "data":{"reason":"challenge_. Rejected handshakes are kept in the request log as unverified, with the rejection cause VERIFICATION_FAILED. Find yours in the dashboard or with:
hookdeck gateway request list --source-id <source id> --verified false
Open one with hookdeck gateway request get <request id> to see the headers and body your server sent, then check the usual causes. The source answers Invalid signature for all of them:
| What you find | Likely cause |
|---|---|
| The timestamp is current | Signing with the wrong secret; signing re-serialized JSON instead of the exact bytes sent; signing something other than webhook-id.webhook-timestamp.body; or using the secret without base64-decoding the part after whsec_ |
| The timestamp is 13 digits, or more than 5 minutes off | webhook-timestamp in milliseconds, or a clock that's wrong. A correct signature over a bad timestamp still gets 401 |
| No request in the log | Your server didn't send a handshake, or refused the URL before trying |
Step 4: Trigger an event and inspect it
Do whatever makes your server emit the event, such as placing an order. The delivery appears as a line in the hookdeck listen terminal:
2026-11-17 14:21:27 [200] POST http://localhost:4000/ (7ms) → https://dashboard.hookdeck.com/events/evt_oJSElCJ2d3pUGLadT4
Select it and press d to see the full request; H copies the headers, B the body and C the whole request. The CLI forwards your server's headers and body unchanged, and adds its own X-Hookdeck-* headers and an Idempotency-Key.
Check each part against SEP-3415:
| Part | What to check |
|---|---|
webhook-id | Present, and the same on every retry of this delivery. SEP-3415 makes it a per-delivery ID; OpenAI's guide expects it to equal eventId |
webhook-timestamp | Unix seconds, new on every attempt |
webhook-signature | v1,<base64>; one entry per valid secret during rotation |
X-MCP-Subscription-Id | Equal to the id that events/subscribe returned |
| Body | eventId, name, timestamp, data and cursor; data matches your payloadSchema; 256 KiB or less |
Your receiver's output confirms the signature from the subscriber's side. A pass there means the bytes reached your machine exactly as your server signed them:
{
'webhook-id': 'msg_QXjPq9mP9LJsmGG0raccNA',
'webhook-timestamp': '1794924318',
'webhook-signature': 'v1,gpFPrVE0wUdspoWSqsfFsymLwKPnVZzFBrWORP0WPvo='
} subscription: sub_1d5fb712e33e66946e2abe96cc677e76
signature OK {
eventId: 'evt_ord_0ec73f7bb097_e9ed9aa8',
name: 'order.created',
timestamp: '2026-11-17T14:05:18.297Z',
data: { orderId: 'ord_0ec73f7bb097', total: 150, currency: 'USD', highValue: true, ... },
cursor: null
}
Then check your filters: trigger an event that doesn't match the subscription's arguments, such as an order in EUR. Nothing should arrive, and the source's request log should show no new request.
Step 5: Replay deliveries
You don't need to trigger a new order every time you change your receiver. Replay a stored delivery instead:
- In the
hookdeck listenterminal, select the delivery and pressr. - From any terminal, run
hookdeck gateway event retry <event id>, using theevt_...ID at the end of the line's dashboard link.
A replay forwards the stored request, headers included, so it tests two receiver rules:
- Duplicates. The replay carries the same
webhook-id. A receiver that deduplicates should acknowledge it and not process it again. - The 5-minute window. The replay keeps the original
webhook-timestamp. Replay a delivery more than 5 minutes old, and the example receiver rejects it withMessage timestamp too old, as SEP-3415 recommends. To check the payload handling instead, skip the timestamp check while you test.
Step 6: Test refreshes and unsubscribes
Call events/subscribe again with the same name, arguments, URL and secret. Your server should return the same id with a later refreshBefore. Whether it sends a new handshake depends on your server: Outpost, for example, remembers a passed check for each callback URL and doesn't repeat it. A passed handshake isn't kept in the request log, so check your server's own logs to see whether it sent one.
Then call events/unsubscribe with the same name, arguments and URL, trigger another matching event, and check that nothing arrives.
If the CLI wasn't running
While no hookdeck listen is connected, Hookdeck still stores each request but creates no event for it, and logs it as ignored. Your server still sees 200. Find the request with hookdeck gateway request list --source-id <source id>, and once the CLI is running again, retry it:
hookdeck gateway request retry <request id>
Clean up
Unsubscribe, stop listen, then delete the source so nothing else can deliver to it. That removes the connection too, but not the CLI destination listen created, so delete that as well:
hookdeck gateway source delete <source id> --force
hookdeck gateway destination list --name cli-mcp-events-test
hookdeck gateway destination delete <destination id> --force
Limits
- Your server's retries aren't exercised. Hookdeck answers
200once it has stored a delivery, so failures on your machine never reach your server. Usemcp-dev checkfor retry and410/413handling. - Event deliveries aren't checked for freshness at the source, only the handshake is. Your receiver applies the 5-minute window.
- A source holds one secret, so you can't test secret rotation, where your server signs with both the old and new secret for a while.
- Requests over 2.5 MiB are verified after the
200, so a bad signature on one doesn't reach your server as a failure. SEP-3415 says delivery bodies should be 256 KiB or less. - This tests webhook mode only. Poll and push delivery don't use a callback URL.
Related resources
- What are MCP Events?
- MCP Events guides and demos, Hookdeck's hub for MCP Events
- Use Event Gateway as a forward proxy for MCP Events, for agents that receive events in production
- Send MCP Events webhooks with Outpost, to have Outpost handle delivery for your server
- Hookdeck CLI reference
FAQs
Can I test MCP Events with hookdeck listen on its own?
No. A source that hookdeck listen creates answers every request with its own 200 body, so your server's verification challenge never comes back and events/subscribe fails. Create an MCP_EVENTS source that holds the subscription's secret first. That source checks the signature and echoes the challenge, and hookdeck listen then forwards the deliveries from it.
Why doesn't the verification challenge reach my local receiver?
The MCP Events source answers it in Hookdeck, and a challenge that passes isn't kept in the request log. Only event deliveries are forwarded to localhost. If the challenge fails, the source answers 401 and logs the request as unverified, with the rejection cause VERIFICATION_FAILED.
Does this test my MCP server's retries?
No. Hookdeck answers 200 once it has stored a delivery, whatever your local receiver does, so your server never sees a failure. Use Outpost's mcp-dev check to test your retry schedule and your handling of 410 and 413.
Why does a replayed MCP event fail signature verification?
A replay keeps the original webhook-timestamp, and Standard Webhooks receivers reject a timestamp more than 5 minutes old. The signature itself still matches. Skip the timestamp check while you test, or trigger a new event.
Webhook infrastructure, managed for you
Hookdeck handles ingestion, delivery, observability, and error recovery — so you don't have to.