Skip to main content

Automation and Agents

How to Implement MCP Events in ChatGPT: Event-Triggered Automations

Build the documented MCP Events flow from subscription to signed delivery, then test retries, access changes, and the result in the subscribed ChatGPT chat.

OpenAI ChatGPT mark beside a terracotta event chime, notification pulses, and a hand receiving a task token on a near-black field.
On this page
  1. What an event subscription actually does
  2. Check the supported environment first
  3. Advertise events through MCP discovery
  4. Accept a subscription with the documented method
  5. Verify the callback before application delivery
  6. Construct the event body that ChatGPT expects
  7. Sign each delivery with Standard Webhooks
  8. Handle acknowledgments, retries, and ordering
  9. Test the user visible workflow
  10. Protect actions triggered by events
  11. What to remember

To implement MCP Events in ChatGPT, your plugin's MCP server must advertise events, accept an authorized subscription from ChatGPT, verify its callback, and send signed notifications when a matching change occurs. ChatGPT then handles the event in the subscribed chat under the user's instruction. OpenAI introduced support for the proposed MCP Events specification at DevDay 2026, with watching a project board and drafting plans for new tasks as its example. OpenAI's announcement describes that use case.

For a developer, the useful question is whether the entire subscription survives ordinary operating conditions: a restart, an expired lease, a failed delivery, or a revoked account. This guide follows OpenAI's current implementation documentation, checked October 7, 2026. The examples and tests below are implementation guidance, not a claim that Rise has benchmarked a working integration.

The integration uses MCP protocol version 2026-07-28, which OpenAI calls MCP 2.0. Its supported portion of the draft covers webhook delivery and callback verification. Polling, streaming, and the draft's gap and terminated control notifications are outside the ChatGPT integration. Treat the MCP Events design sketch as a proposal, and use OpenAI's guide for the behavior available in ChatGPT.

Key Takeaways- ChatGPT subscribes to events exposed by the connected plugin server; the server sends signed notifications to ChatGPT's callback.- A successful webhook receipt and a completed user task are separate outcomes. Test both.- Keep subscription state, delivery retries, and tool writes safe across repeated requests, restarts, and access changes.

What an event subscription actually does

An event starts with a user instruction, such as asking ChatGPT to watch a project board for a new task and draft a plan when one appears. The connected plugin server must expose that event to the user's account. ChatGPT discovers the event and asks the server to subscribe with a filter, callback URL, and signing secret. When the application detects a matching event, its server sends one signed event to the callback. ChatGPT acknowledges receipt and processes the event asynchronously in the subscribed chat according to the user's instruction. The user and workspace controls still define what the plugin may access and do. OpenAI announcement; OpenAI MCP Events guide.

A hook carries an event card toward a receiving tray. View image detail

Choose Actual size to read the graphic closely.

The application developer owns event production and durable subscription state. The server checks which source changes match the filter and whether the connected account may monitor them. ChatGPT supplies the destination and signing secret. Start with one record type and one narrow filter so the first test has an unambiguous result: the expected event reaches the subscribed chat, while an unrelated event does not.

An event is a notification, not a command from the source application. A task title or document comment can contain text written by someone other than the subscriber. Keep those fields as data and let the user's original instruction and the plugin's permissions determine what happens. OpenAI's guide explicitly says not to put instructions to the model inside the event payload. OpenAI MCP Events guide; OpenAI plugin security guide.

Check the supported environment first

OpenAI documents MCP Events for Work chats on ChatGPT web, Work chats in the desktop app with Cloud selected, and dots. Workspace controls for plugins and event triggered tasks apply. A developer should verify the target workspace and plugin configuration before diagnosing the server. The server needs MCP 2.0 protocol version 2026-07-28, persistent storage for subscriptions, and outbound HTTPS access to the callback URLs supplied during subscription. A prototype that forgets subscriptions on restart or cannot make outbound connections will appear to work during discovery but cannot deliver reliably. OpenAI MCP Events guide.

Use an authenticated MCP endpoint for event methods and tools. Event discovery is scoped to what the connected account may see. If the account can monitor one project but not another, the event catalog and subscription validator must enforce that boundary. Make the filter narrow enough to prevent irrelevant events from reaching a chat. For a comment.created event, a document ID is a clearer filter than a broad subscription to every document in an organization.

A narrow subscription filter selects matching events before delivery. View image detail

Choose Actual size to read the graphic closely.

Choose the work before wiring the trigger. A comment arriving is an observable change; whether that comment requires a project decision is a separate judgment. A narrow first workflow could collect the comment and prepare a draft response for its owner. Rise's Work Worth Doing automation test helps decide whether the task is stable enough to automate and what should remain with a person.

The first technical step is advertising an events capability in the server's server/discover response. OpenAI's example includes supportedVersions: ["2026-07-28"] and an events object alongside tools. The same authenticated endpoint must implement three methods: events/list, events/subscribe, and events/unsubscribe. OpenAI MCP Events guide.

events/list describes available event types. Each definition has a stable name, a clear description, supported delivery modes, an inputSchema for subscription arguments, and a payloadSchema for the event's data object. For example, a document comment event can require a document_id argument and return a data object containing document and comment IDs, text, and a URL. The event definition should say what the event means, including whether edits or deletions create new occurrences. If the catalog has multiple pages, implement the documented cursor mechanism rather than silently truncating it. OpenAI MCP Events guide.

Schema design also affects privacy. If the event can identify a sensitive record, deliver the smallest useful summary and expose a read tool for the full record. The event can then tell ChatGPT that something changed without copying an entire document, customer record, or log into the callback body. Match payloadSchema to what the server will actually send. Reject or repair events that fail that schema before delivery.

The delivered data must fit the payload schema advertised by the event definition. View image detail

Choose Actual size to read the graphic closely.

Accept a subscription with the documented method

When the user asks to monitor an event, ChatGPT calls events/subscribe on the plugin's MCP server. The request includes name, arguments, a delivery object with mode webhook, the callback url, and a whsec_ signing secret. It can also include a cursor for replayable events. The exact protocol example and response fields are in OpenAI's guide.

Before accepting, the server checks the authenticated user's right to subscribe to that event and filter. It validates the event name and arguments against its definition, checks that the supplied whsec_ secret decodes to the required 24 to 64 bytes, and validates and verifies the callback address. It then stores the owner, filter, callback, signing secret, and expiration. OpenAI directs servers to derive a deterministic subscription ID from the authenticated principal, callback URL, event name, and arguments. Creation should be idempotent: a second matching request updates the existing subscription. Canonicalize JSON arguments when comparing them so a change in key order does not create a duplicate. OpenAI MCP Events guide.

The response returns an ID, refreshBefore, cursor, and truncated. refreshBefore represents the expiration actually granted. The request can include ttlMs: omission uses the server's default lifetime, a number requests that many milliseconds, and null requests no expiration. A server may enforce a minimum lifetime to avoid excessive refresh requests. Return refreshBefore: null only when granting the no-expiration request; otherwise return a finite expiration and stop delivery when it passes. OpenAI's subscription lifecycle guidance.

Replay is a separate capability. Return cursor: null if the event cannot be replayed. For replayable events, retain the history needed to honor a cursor and report truncated: true when that history is unavailable. A cursor returned in a response or event must not skip events still awaiting delivery. Decide retention from the actual application needs, and explain interruption recovery honestly to the user.

Verify the callback before application delivery

OpenAI requires verification of the callback before sending application data. The server sends a signed verification control envelope with a fresh, single use challenge. Its request has a unique webhook-id, plus webhook-timestamp, webhook-signature, and X-MCP-Subscription-Id. ChatGPT echoes the challenge in a successful response. The server requires a 2xx response and compares the returned challenge in constant time. OpenAI MCP Events guide.

Two endpoints exchange the same round challenge token on separate outgoing and return paths. View image detail

Choose Actual size to read the graphic closely.

Callback validation is also a network security boundary. Require HTTPS. Resolve and validate the destination at connection time, block private, local, and otherwise nonpublic addresses, preserve the original host name for TLS verification, and do not follow redirects. Apply these checks to the verification request and to later event deliveries. A one time validation when the subscription is created does not cover a DNS change before a later delivery. OpenAI's guide specifies this pattern and a categorized CallbackEndpointError if verification fails. OpenAI MCP Events guide.

Verification results can be cached for a bounded period by authenticated principal and URL, as OpenAI recommends, so repeated matching subscriptions do not repeatedly challenge the same destination. Cache scope matters: a successful challenge for one account cannot prove that another account may subscribe to the same application data. Keep authorization checks on every subscription even if the callback was recently verified.

Construct the event body that ChatGPT expects

An application event has eventId, name, timestamp, data, and cursor. The event ID is unique and stays the same across retry attempts. The timestamp is the event occurrence time in ISO 8601 with a time zone. name matches the subscribed event, and data conforms to that event's payloadSchema. Application fields belong inside data; a top level type is reserved for a protocol control notification. OpenAI MCP Events guide.

The same event identity follows a retry while a clock marks its original time and a separate envelope represents a protocol control message. View image detail

Choose Actual size to read the graphic closely.

For example, a comment.created event can include the comment ID, document ID, text, and a link in data. If the comment is long, send a short summary and let an authorized read tool retrieve the rest. A stable ID lets the receiver recognize a retry; a stable event name lets the receiver associate the notification with the subscription; and a cursor, when supported, lets the server resume after an interruption. Design these values around real application records rather than generating a new ID every time a delivery is retried.

The source application may use an internal queue to separate its database transaction from outbound delivery. That queue is an application architecture choice. Keep that infrastructure separate from the documented subscription and delivery contract. A queue or managed event bus should provide the durability and retries your application needs.

Sign each delivery with Standard Webhooks

ChatGPT verifies deliveries using Standard Webhooks. OpenAI requires Content-Type: application/json, webhook-id equal to the body's eventId, webhook-timestamp as signing time in Unix seconds, webhook-signature as the Standard Webhooks signature, and X-MCP-Subscription-Id equal to the ID returned by events/subscribe. OpenAI MCP Events guide.

The Standard Webhooks signed content includes the message ID, signing timestamp, and exact body bytes. Serialize the JSON body once and use those exact bytes for signing and transmission. The Standard Webhooks specification documents the msg_id.timestamp.payload construction and versioned, base64 signature format. Prefer its maintained library over hand written parsing and HMAC code. OpenAI's Node example uses the standardwebhooks package to sign a delivery and supplies a webhookFetch function that validates callback addresses on each connection and refuses redirects. Standard Webhooks specification; OpenAI MCP Events guide.

One band binds a message identifier tag, signing-time clock and blank body sheet. View image detail

Choose Actual size to read the graphic closely.

Signing does not make event text trustworthy as an instruction. It proves that the delivery came from a party with the subscription's secret and that the signed bytes were not changed in transit. The originating record may still contain attacker controlled text. Keep those concerns separate in code and review: signature verification at delivery, authorization at subscription and tool access, and safe treatment of event data during model use.

Handle acknowledgments, retries, and ordering

A 2xx response acknowledges webhook receipt; it does not report that ChatGPT completed the user's task. OpenAI says to send one event per request and keep the full request body at or below 256 KiB. ChatGPT can group separately delivered events into one task run according to the task's batching settings. OpenAI MCP Events guide.

For transient delivery failures, retry with exponential backoff and bounded attempts. Preserve eventId, but generate a fresh signing timestamp and signature for each attempt. Do not retry 410 or 413 responses. Record the attempt result without logging the signing secret or sensitive event body. This gives operators enough information to distinguish an expired subscription, an oversized payload, a temporary network failure, and a successful receipt. OpenAI MCP Events guide.

Events can arrive out of order. OpenAI specifically advises idempotent write tools so repeated calls do not duplicate changes. If the source needs strict ordering for one record, its own event model can include a sequence value and durable reconciliation process. Document that behavior as part of your application. The ChatGPT integration does not supply a universal sequence field or a missing-event retrieval guarantee. OpenAI MCP Events guide; MCP design sketch.

Subscription refresh is separate from event retry. ChatGPT calls events/subscribe again before refreshBefore, using the same identity and the last saved cursor. Update the existing subscription and its granted expiration. When the refresh supplies a replacement signing secret, replace the stored secret and sign with both keys during a short rotation window, using Standard Webhooks' space-separated signatures. Recheck account access during the subscription's lifetime and stop delivery if it is revoked. OpenAI MCP Events guide.

For events/unsubscribe, match the original event name, arguments, and callback URL, authorize the request against the connected account, and stop that subscription. Return an empty result. Make repeated unsubscribe requests safe, just as repeated subscription creation must be safe. A stopped monitor should stay stopped after a server restart.

A person lifts a terracotta clasp from one curved path, leaving a clear gap. View image detail

Choose Actual size to read the graphic closely.

Test the user visible workflow

Begin with discovery. Confirm that ChatGPT calls server/discover and events/list, that the event definition appears on the plugin page, and that a rescan reflects event changes. Then ask from a supported Work chat to monitor one narrow event. Confirm that your server receives events/subscribe with the expected authenticated principal and filter, validates the callback, and stores one deterministic subscription. A second identical request should update it rather than create another. OpenAI MCP Events guide.

Create a test event in the connected application and inspect the delivery at the source server. Confirm that the event body matches its schema, the same serialized bytes were signed and sent, the correct subscription ID accompanies the Standard Webhooks headers, and the destination passed connection time address checks. Observe the HTTP response as a receipt result. Check the subscribed chat for the resulting task separately. If the task acts on the event, verify that it follows the user's instruction and the connected account's tool permissions.

Test failures deliberately. Retry a transient network failure with the same event ID and a new signing timestamp. Verify that a 410 or 413 stops retries and produces a diagnostic. Revoke the source account's access and confirm delivery stops. Refresh the subscription and confirm that it retains the right identity and cursor. Unsubscribe and confirm that no more application events are sent. These checks reveal problems that a single successful demo does not exercise.

Measure performance in your own environment. Record source commit time, queue delay, outbound attempt time, receipt status, and when the user-visible task actually completes. Report percentile latency with workload, sample size, region, and test setup. A fast receipt can coexist with a slow or unsuccessful task, so one HTTP timing cannot summarize the workflow. Keep a separate count of expected outputs that were actually completed and checked.

For the hypothetical document-comment workflow, the result check is concrete: the draft must address the right comment on the right document, use the connected account's permitted context, and remain a draft if that is what the user requested. Deliver a duplicate event and inspect the output again. If the task writes anything, confirm that a repeated tool call cannot create a second copy. These are proposed acceptance checks, not measured results.

A person inspects a draft page through a terracotta lens, checking its scope. View image detail

Choose Actual size to read the graphic closely.

Protect actions triggered by events

An event can carry malicious instructions in a comment, task title, or log line. OpenAI's plugin security guidance recommends defense in depth because prompt injection and malicious inputs can reach the server. Keep event fields in a typed schema, limit tools to the connected user's authorized resources, and verify tool arguments at the server. A JSON wrapper alone cannot make hostile text safe. OpenAI plugin security guide; OWASP MCP Security Cheat Sheet.

For high-impact writes, define an approval and execution policy before enabling the workflow. OWASP's MCP security guidance recommends explicit confirmation for destructive, financial, or data-sharing operations, including showing the full tool parameters. That is security guidance, not an MCP Events approval-token format. Enforce account authorization and idempotency in the tool backend, even when a model proposes the call.

A reviewer needs to see the action, affected account, target record, and proposed change. Rise's guide to governing a personal AI agent before it can act develops that ownership and review decision. For this implementation, establish who can stop the subscription and how a failed or uncertain write will be investigated before widening its scope.

What to remember

Start with one event, one filter, and one task whose correct result is easy to inspect. Verify discovery, subscription creation, callback challenge, signed delivery, and the output in the subscribed chat. Then repeat the workflow through a restart, a transient failure, a refresh, and an unsubscribe. Those checks give you a basis for expanding the integration. A green webhook response alone does not.

Checked for this article

Sources

  1. OpenAI DevDay 2026 Recap
  2. OpenAI MCP Events implementation guide
  3. MCP Events draft design sketch
  4. Standard Webhooks specification
  5. OpenAI plugin security guidance
  6. OWASP MCP Security Cheat Sheet

Keep reading

All articles