---
title: "Create or refresh an MCP Events subscription"
method: POST
path: "/v1/event-subscriptions"
tags: ["Webhooks"]
---

# Create or refresh an MCP Events subscription

`POST /v1/event-subscriptions`

## Request

- Base URL: `https://api.deadsimple.email`
- URL: `https://api.deadsimple.email/v1/event-subscriptions`
- Auth: HTTP bearer

Backs `events/subscribe` on the hosted MCP server (OpenAI's MCP Events, used by ChatGPT Work chats and dots). Idempotent: the subscription id is derived from the account, callback URL, event name and arguments, so the same request refreshes the same subscription. A new subscription, or one whose secret changed, is activated only after the callback answers a signed `{"type":"verification","challenge":...}` POST by echoing the challenge. Events are then POSTed as `{eventId, name, timestamp, data, cursor}` with Standard Webhooks headers (`webhook-id` = eventId, stable across retries) and `X-MCP-Subscription-Id`. 410 and 413 responses are not retried; a 410 deletes the subscription. Field names follow the MCP Events spec.

## Request body

- object
  - `name` 'message.received' | 'message.bounced', required
  - `arguments` object: Filters. `inbox_id` (both events; omitted = every inbox the credential can see, required for inbox-scoped keys), `from_contains` and `subject_contains` (message.received only, case-insensitive substrings).
    - `inbox_id` string
    - `from_contains` string
    - `subject_contains` string
  - `delivery` object, required
    - `mode` 'webhook'
    - `url` string, uri, required: HTTPS callback; must resolve to public addresses.
    - `secret` string, required: Standard Webhooks secret, `whsec_` + base64 of 24-64 bytes.
  - `ttlMs` number, nullable: Requested lifetime. Omitted = 30 days; capped at 90 days; null (no expiry) is granted as 90 days.
  - `cursor` unknown

## Response `201`

Subscription active

- object
  - `id` string
  - `refreshBefore` string, date-time
  - `cursor` unknown
  - `truncated` boolean

## Other responses

- `400`: Unknown event, unknown argument, bad secret or callback URL
- `422`: `callback_verification_failed`: the callback did not echo the challenge. `details[0].reason` is `challenge_failed` or `timeout`.

---

[API](https://skmtc.dev/deadsimple/apis/dead-simple-email-api.md) · [All operations](https://skmtc.dev/deadsimple/apis/dead-simple-email-api/llms.txt) · [OpenAPI document](https://skmtc.dev/deadsimple/apis/dead-simple-email-api/revisions/c697881be131?raw)