mcp-webhook-events

MCP Events for Python MCP servers. Let ChatGPT watch something in your app and act when it changes.

On 29 September 2026 OpenAI added MCP Events to ChatGPT. A user can ask ChatGPT to watch something in your app, ChatGPT subscribes through your MCP server, and your server sends a signed webhook when it changes. ChatGPT then does whatever the user asked.

The official Python MCP SDK (mcp 2.2.0) does not support this yet. Neither does the TypeScript SDK (1.32.0). This package adds it to a server built on the official Python SDK, without forking or patching the SDK.

pip install mcp-webhook-events

Proven with the real ChatGPT

Tested on 2 October 2026 against a live server (UK Business Check, which watches UK companies):

1. After "Refresh tools", ChatGPT listed the server's company.status_changed event next to its tools.
2. In a Work chat, "watch company 00445790" made ChatGPT call events/subscribe. The callback was verified with a signed single-use challenge, and ChatGPT echoed it correctly.
3. A test event was signed and posted. ChatGPT's receiver returned 200, and seconds later ChatGPT posted in the chat by itself: "TEST — TESCO PLC (00445790): the service owner sent a test event; nothing about the company actually changed."

Quick start

from mcp.server import MCPServer
from mcp_webhook_events import EventDefinition, McpEvents

mcp = MCPServer("Ticket watcher")

events = McpEvents(mcp, store="events.sqlite3", definitions=[
    EventDefinition(
        name="ticket.updated",
        description="A support ticket you are watching was updated.",
        input_schema={"type": "object", "properties": {"ticket_id": {"type": "string"}},
                      "required": ["ticket_id"], "additionalProperties": False},
        payload_schema={"type": "object",
                        "properties": {"ticket_id": {"type": "string"}, "summary": {"type": "string"}},
                        "required": ["ticket_id", "summary"], "additionalProperties": False},
    ),
])
events.install()   # adds events/list, events/subscribe, events/unsubscribe and the `events` capability

app = mcp.streamable_http_app(stateless_http=True, json_response=True)

When something changes, from anywhere that can open the same store (a cron job, a webhook handler, a worker):

events.publish("ticket.updated", {"ticket_id": "T-1", "summary": "Customer replied"})
events.deliver_pending()   # sends now. Call it again on a timer to retry failures

By default an event goes to every live subscription whose arguments match fields of the same name in the event data. Pass matches= to an EventDefinition for anything cleverer.

ChatGPT dots: get_recent_events

As of 3 October 2026, a ChatGPT dot that subscribes to your event gets woken up when you deliver it, but the event's data never reaches the dot (reported here). Work chats on the web do see it. Until OpenAI fixes that, turn on the workaround:

events.install(recent_events_tool=True)

This adds one read-only tool, get_recent_events. A dot that wakes up without the data calls it and gets the latest events from its subscriptions, newest first, with the full data and whether each was delivered. It takes event_name, event_id, arguments (the same values it subscribed with, matched with your event's matches rule) and limit (1 to 50, default 5). History is kept for 7 days.

Each caller only sees events from their own subscriptions. That needs principal= on McpEvents: a function that returns a stable user ID from the request context. If your server has no logins and you leave it out, every caller looks the same, so the tool refuses to list everything and asks for an event_id or the arguments instead. A dot always knows what it subscribed to, so it still gets its data, but nobody can browse other people's watches.

A full example is in examples/watch_server.py.

What it handles for you

Everything on OpenAI's MCP Events page that a server has to do:

Not included, because ChatGPT does not support them either: polling, streaming, replay cursors and the draft's gap and terminated notifications.

Three things that had to be worked out

These are the parts that are not obvious from the documentation, in case you are building this yourself.

1. Custom methods are allowed. The SDK's low-level server has add_request_handler(method, params_type, handler), and it accepts events/* methods over the 2026-07-28 Streamable HTTP transport. No fork is needed.
2. Clients must send Mcp-Method. On the modern transport, a request without an Mcp-Method header matching the body's method gets rejected with -32020. ChatGPT sends it, but your own test client needs to as well.
3. The SDK drops unknown capabilities. ServerCapabilities ignores unknown keys, and spec results are cleaned against the schema, so events: {} never reaches the wire if you put it in the result. This package adds it in middleware, after the result is serialised.

Testing

pip install -e ".[test]"
python -m unittest discover -s tests -v
python tests/mutation_check.py     # breaks the code 36 ways, and every one must be caught

The tests run a local receiver that plays ChatGPT. It checks every signature with the official Standard Webhooks verifier rather than this package's own code. mutation_check.py proves the tests catch real faults: unverified callbacks, wrong signatures, ignored filters, retrying a 410, leaking to private addresses and so on.

Status

Version 0.2.0 (adds get_recent_events for ChatGPT dots). MCP Events is still a draft extension, so details may change, and the official SDKs will probably add support at some point. Until they do, this is a small, tested way to use it today.

Issues and pull requests are welcome.

Licence

MIT. Made by Shaun Owen.