MCP Events in ChatGPT: How Webhook Triggers Work
OpenAI added support for the proposed MCP Events spec, so an MCP server can push updates into ChatGPT. The documented limits, the signing recipe, and what builders should watch.
MCP Events let ChatGPT subscribe to updates from an MCP server, so a new message, a content update, or a status change can start an automation while you are away. OpenAI announced support for the proposed MCP Events specification at DevDay on 29 September, and its developer documentation spells out how a server has to behave. The short version: delivery is webhook-only, every request is signed, and the rules about where a server may deliver are strict.
What MCP Events are
Until now the usual pattern with MCP was pull. ChatGPT calls a tool on your server when a conversation needs it. Events reverse the direction: the server tells ChatGPT that something changed. If the basics of the protocol are new to you, start with our explainer on what the Model Context Protocol is.
According to the docs, MCP Events needs MCP 2.0 with protocol version 2026-07-28, and the server implements three methods: events/list to describe the available events and filters, events/subscribe to create or refresh a subscription, and events/unsubscribe to stop one. It works through ChatGPT plugins connected to MCP servers and requires the connected account to authorize the events requested. The Runtime Wire keynote roundup describes the use case as automations triggered by changes in external apps.
How a delivery works
ChatGPT asks the server what it can emit with
events/list.It subscribes to the events it wants with
events/subscribe, supplying a callback.Before any real data flows, the server verifies the callback by sending a signed request carrying a fresh, single-use, short-lived challenge. The other side has to echo it back.
After that, each event arrives as one signed POST.
The limits in the docs
Item | What the docs say |
|---|---|
Delivery | Webhook only, no polling or streaming |
Payload | One event per request, body no larger than 256 KiB (262,144 bytes) |
Timeout | 10 seconds |
Signing secret | A base64 value that decodes to 24 to 64 bytes |
Headers |
|
Addresses | Block private, local and other non-public addresses, and do not follow redirects |
Signing an event
The docs say events use Standard Webhooks HMAC signatures. The Standard Webhooks spec defines the recipe: concatenate the message ID, the timestamp and the body with full stops, sign that with HMAC-SHA256, and send the result in webhook-signature as v1, followed by the base64 signature. Secrets are base64 encoded and conventionally prefixed whsec_.
Here is a minimal Python sketch of the signing side, written from the spec. I have not run it against ChatGPT's receiver, which is in preview, so test it against the verification challenge before trusting it.
import base64, hashlib, hmac, json, time, uuid
def sign_event(secret: str, event: dict) -> dict:
body = json.dumps(event, separators=(",", ":")).encode()
if len(body) > 262_144:
raise ValueError("event exceeds the 256 KiB cap")
msg_id = "msg_" + uuid.uuid4().hex
ts = str(int(time.time()))
key = base64.b64decode(secret.removeprefix("whsec_"))
signed = f"{msg_id}.{ts}.".encode() + body
sig = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
return {
"body": body,
"headers": {
"webhook-id": msg_id,
"webhook-timestamp": ts,
"webhook-signature": f"v1,{sig}",
},
}The spec is blunt about one trap: the payload you send must be byte for byte the payload you signed, so serialize once and reuse the bytes. On the receiving side it asks for a constant-time signature comparison, a timestamp tolerance to block replays, and the webhook-id as an idempotency key.
What builders should watch
If you run an MCP server for your own app, events are how "a new order arrived" or "a ticket changed" can reach a ChatGPT automation without a user asking first. Our comparison of MCP and plain REST APIs for agents covers when an MCP server is worth having at all, and the general hygiene for receiving callbacks lives in how to add webhooks to an AI-built app.
Two cautions. The specification is described as proposed, and the docs pin one protocol version, so expect change. And event-driven automation removes the human from the loop, the same shift we describe in what an always-on AI agent is. Decide in advance what a runaway stream of events is allowed to trigger.
On the sending side, design for duplicates and bursts from day one. Give every event a stable ID so a retry reuses the same webhook-id, batch related changes into a single event where the meaning allows, and keep each payload small enough that the 256 KiB cap is never a surprise. A server that sends a hundred events for one edit will be a bad neighbour for whoever subscribed to it.
FAQ
Do MCP Events use polling?
No. The docs describe delivery as webhook only, with no polling or streaming.
What is the maximum MCP Events payload size?
One event per request, with a complete body no larger than 256 KiB (262,144 bytes).
Do I need MCP 2.0 to use MCP Events in ChatGPT?
The docs require MCP 2.0 with protocol version 2026-07-28, and the server must handle events/list, events/subscribe and events/unsubscribe.
Can an MCP Events callback point at localhost?
No. The docs tell servers to block private, local and other non-public addresses and not to follow redirects, so the callback needs a public endpoint.
How did this land?
About the author
Senior Editor, AI & Product
Cecilia leads the Swarmz editorial desk. She has spent a decade turning complex AI and product topics into writing people actually finish, and she owns the blog's quality bar.
