Events

An assistant connected over MCP can do more than
answer when asked. It can watch the workspace and act as soon as something
happens: brief you when new recommendations land, check a competitor’s move the
morning it is spotted, or summarise a project the moment it closes.

This uses MCP events. ChatGPT supports them today, and any client that
implements the MCP Events extension can use them too.

What an assistant can watch

Event Fires when Narrow it by
New recommendations (recommendation.created) The morning’s data lands new recommendations: reorders, price moves, range calls Remit, kind
Competitor price moves (competitor_price.changed) Price tracking first spots a competitor cut, a stockout, one retailer following another, or the market index crossing yours Retailer, kind of move, SKU
Project changes (project.updated) A project is created, closed or reopened, or its supplier order is finalised Project, kind of change
Data refreshed (data.refreshed) A new day of sales, stock and supplier data is in, so earlier figures are out of date —

Competitor price moves appears only in workspaces with price tracking.

Ask ChatGPT to watch

Connect ChatGPT first (ChatGPT). Then, in a
Work chat, say what to watch and what to do:

  • “When new recommendations land in my Toys remit, give me the three that matter most.”
  • “Tell me when Big W cuts a price on anything I track, and say whether we should follow.”
  • “When the Lego supplier negotiation closes, draft a summary for the team.”
  • “Each morning, once the data has refreshed, send me a trading brief.”

ChatGPT shows the subscription in the chat and acts each time the event fires.
To stop, ask it to stop watching, or end the connection under Settings → AI &
agents. Ending the connection stops every subscription it made.

If nothing arrives

  • Use a Work chat. ChatGPT offers events only in Work chats (on the web, or
    in the desktop app with Cloud selected), not in ordinary chats.
  • Allow about a minute. Twelfth checks for new events every 30 seconds.
    Recommendations and refreshed data arrive when the morning’s data lands, not
    the moment you subscribe.
  • Check your scope. Nothing is sent for a remit you don’t hold or a SKU you
    don’t cover, so a quiet subscription may just mean nothing in your scope
    changed.
  • Check the connection’s tools. If you didn’t allow a tool when you
    connected, the events that depend on it aren’t offered. Reconnect from
    Settings → AI & agents and allow it.
  • Ask ChatGPT what it’s watching. A subscription lasts up to a day and
    ChatGPT renews it while the chat still wants it. If the chat has moved on,
    ask it to start watching again.

What an assistant receives

An event says what happened and where to look: ids, a title, a link into
Twelfth, and the tool that reads the detail. It does not carry sales,
margin or cost figures. The assistant fetches those with a normal tool call,
which applies your workspace permissions and is recorded like any other call.

Events follow the same scope as the tools:

  • A connection made by signing in sees only events in your remits. A
    recommendation in another buyer’s remit, or a price move on SKUs you don’t
    cover, is never sent.
  • A connection is offered only the events whose reading tool it may use. If a
    connection can’t list projects, it can’t watch them either.
  • Access is checked again every time an event is delivered. If your access
    changes, deliveries change with it. If you leave the workspace or the
    connection ends, they stop.

For developers

Twelfth implements the MCP Events extension on its 2026-07-28 endpoint at
https://api.twelfth.ai/mcp. server/discover advertises
capabilities.events. Every events method needs the same OAuth token or
workspace key as the tools.

  • events/list returns the events this connection may watch. Each has its
    delivery modes, an inputSchema (the filter arguments) and a
    payloadSchema (the event’s data).
  • events/poll is stateless. Call it first with cursor: null and keep the
    cursor each poll returns. It also returns hasMore and nextPollMs, and
    truncated: true when the cursor is older than seven days (or older than your
    maxAgeMs).
  • events/subscribe registers a webhook:
    delivery: { mode: "webhook", url, secret }.
    • The url must be public HTTPS.
    • The secret is yours: whsec_ plus base64 of 24–64 random bytes.
    • Before activating, Twelfth POSTs a signed
      {"type":"verification","challenge":…}. Echo the challenge in a 2xx
      response, either as the body or as {"challenge": …}.
    • Subscribing again with the same event, arguments and URL refreshes the
      subscription and returns the same id.
    • A subscription lasts up to 24 hours (refreshBefore); you can ask for less
      with ttlMs.
  • events/unsubscribe takes the same event, arguments and delivery.url.
    Calling it twice is safe.

Each delivery is one POST of one event, { eventId, name, timestamp, data, cursor }, signed with Standard Webhooks:

  • webhook-id, the event’s eventId, unchanged across retries. Deduplicate on it.
  • webhook-timestamp, webhook-signature and X-MCP-Subscription-Id.

Verify the signature with any Standard Webhooks library before trusting the
body:

import { Webhook } from "standardwebhooks";

const event = new Webhook(process.env.TWELFTH_WEBHOOK_SECRET).verify(rawBody, headers);

To see it work end to end, create, close or reopen a project. That raises
project.updated straight away, with no need to wait for a data refresh.

Delivery rules:

  • A 2xx acknowledges the delivery.
  • Twelfth retries other failures after 1 minute, 5 minutes, 30 minutes, 2 hours
    and 6 hours, then gives up.
  • 410 and 413 are never retried.
  • Redirects are never followed.
  • Events may arrive out of order.
  • Generic MCP — the endpoint, tools, prompts and resources
  • ChatGPT — connect ChatGPT
  • API keys — connect with a workspace key
Previous Generic MCP Next Vercel Connect