SVsvix
Endpoint

Subscribe to MCP Events

Changed on

Create or refresh an MCP Events subscription.

post/api/v1/app/{app_id}/mcp-events/subscribe

Request

Path parameters

app_idstring required

The Application's ID or UID.

Example:unique-identifier

Headers

idempotency-keystring

The request's idempotency key

Request body

argumentsobject

The filter arguments of the events/subscribe request, as described by the event's inputSchema (e.g. {"document_id": "doc_123"}). Together with name and the callback URL they identify the subscription

They're stored in the endpoint's mcpEventArguments metadata, but aren't used to filter messages; use channels for that.

See Create a subscription in OpenAI's MCP Events docs.

challengeMode'challenge-response' | 'echo'

How an endpoint must respond to a challenge.

  • challenge-response: the Standard Webhooks challenge-response check. The endpoint must return webhook-challenge-response, calculated from the challenge and its secret.
  • echo: the endpoint must echo the challenge from the request body back as {"challenge": "..."}. This doesn't prove that it holds the secret.
channelsstring[] nullable

Only send messages with one of these channels to the subscription, for example ones derived from arguments. Omit to send all messages of the event type.

namestring required

The event to subscribe to. It must be an existing event type.

secretGracePeriodSecondsinteger nullable

How long the previous secret keeps signing when a refresh changes it, in seconds.

Valid values are between 0 (immediate expiry) and 7 days. The default is 5 minutes.

ttlMsinteger nullable

The requested lifetime of the subscription, in milliseconds. Omit for the default of 7 days, or set to null for a subscription that never expires.

Example request

{
  "channels": [
    "project_1337"
  ],
  "delivery": {
    "secret": "whsec_C2FVsBQIhrscChlQIMV+b5sSYspob7oD"
  },
  "name": "user.signup"
}

Response

cursorstring nullable

Always null, since events can't be replayed.

endpointIdstring required

The Endpoint's ID.

idstring required

The subscription's ID, which is also the UID of its endpoint.

refreshBeforestring date-time nullable

When the subscription expires, or null if it never does.

truncatedboolean required

Always false, since events can't be replayed.

Example response

{
  "endpointId": "ep_1srOrx2ZWZBpBUvZwXKQmoEYga2",
  "id": "unique-identifier"
}

Changes