Search docs

Find a page in the Taskaid docs.

Open app

Events

How an assistant subscribes to Taskaid's events, how each one is delivered, and each event as a client receives it.

Events let an assistant hear about something in your Taskaid as it happens, instead of reading your tasks again to find out. Connecting a client and the scopes it is granted are on the MCP server page.

Taskaid implements the MCP Events extension, an experimental draft from MCP's Triggers & Events working group, with webhook delivery. Assistants that support it, such as ChatGPT, subscribe on your behalf; Reminders in ChatGPT shows the setup.

How events work

Listing. events/list returns each event on this page: its name, a description written for the assistant, the arguments a subscription can take, and the shape of what it carries.

Subscribing. events/subscribe names an event, can narrow it with arguments, and gives an https address and a signing secret. It needs read, the same access as reading your tasks. The first time an address is used, Taskaid posts a challenge to it, and the address must send the challenge back.

Renewing. A subscription lasts up to a day, until the refreshBefore time it returns. The assistant renews it by subscribing again with the same event, arguments and address, which updates that subscription rather than adding another. One it stops renewing lapses on its own.

Delivery. Each event is posted to the address as JSON, signed per Standard Webhooks with the subscription's secret. The body carries eventId, name, timestamp, the event's data, and cursor, which is always null. The webhook-id header is the eventId, the same on a retry, so a receiver can drop a repeat. A delivery that fails is tried once more; a 410 or 413 from the receiver ends it there.

Stopping. events/unsubscribe, with the same event, arguments and address, ends a subscription. Disconnecting the assistant stops delivery at once, without waiting for its subscriptions to lapse.

No replay. An event goes to the subscriptions live when it happens. One made later doesn't receive it.

Reading an event entry

Each definition below is what a client receives from events/list, kept identical to the live server by a test.

  • description is what an assistant reads to decide whether to subscribe.
  • inputSchema is the arguments a subscription can take. Both events take an optional listId, to hear only about one list; a list that isn't yours is refused.
  • payloadSchema is the shape of data in each delivery: the task, without its note. view_task reads the rest, with the access you approved.

task.created

Subscribe to act on a task as soon as it's added, wherever it was added from, instead of searching for what's new.

task.created
{
  "name": "task.created",
  "description": "Occurs when a task is created in the user's Taskaid, from any app or assistant. Pass `listId` to hear only about tasks created in that list.",
  "delivery": ["webhook"],
  "inputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "listId": {
        "description": "Only tasks created in this list. Use `view_lists` to find its id.",
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "payloadSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "url": {
        "type": "string"
      },
      "name": {
        "type": "string"
      },
      "completed": {
        "type": "boolean"
      },
      "starred": {
        "type": "boolean"
      },
      "when": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "description": "Calendar date, \"YYYY-MM-DD\", or null for Inbox."
      },
      "reminder": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "description": "Time of day on the `when` day, \"HH:MM\", or null for none."
      },
      "duration": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "null"
          }
        ]
      },
      "completedAt": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ]
      },
      "updatedAt": {
        "type": "string"
      },
      "source": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ]
      },
      "list": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "emoji": {
                "type": "string"
              }
            },
            "required": ["id", "name", "emoji"],
            "additionalProperties": false
          },
          {
            "type": "null"
          }
        ]
      }
    },
    "required": [
      "id",
      "url",
      "name",
      "completed",
      "starred",
      "when",
      "reminder",
      "duration",
      "completedAt",
      "updatedAt",
      "source",
      "list"
    ],
    "additionalProperties": false
  }
}

task.reminded

Subscribe to act on a task at the time you set. Reminders covers how a reminder moves with its task and when it doesn't go off.

task.reminded
{
  "name": "task.reminded",
  "description": "Occurs at the time set in a task's `reminder`, on its `when` day, in the user's time zone. One subscription can cover every reminder. The event carries the task without its note; `view_task` returns the full task, note included. Pass `listId` to hear only about tasks in that list.",
  "delivery": ["webhook"],
  "inputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "listId": {
        "description": "Only tasks in this list. Use `view_lists` to find its id.",
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "payloadSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "url": {
        "type": "string"
      },
      "name": {
        "type": "string"
      },
      "completed": {
        "type": "boolean"
      },
      "starred": {
        "type": "boolean"
      },
      "when": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "description": "Calendar date, \"YYYY-MM-DD\", or null for Inbox."
      },
      "reminder": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "description": "Time of day on the `when` day, \"HH:MM\", or null for none."
      },
      "duration": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "null"
          }
        ]
      },
      "completedAt": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ]
      },
      "updatedAt": {
        "type": "string"
      },
      "source": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ]
      },
      "list": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "emoji": {
                "type": "string"
              }
            },
            "required": ["id", "name", "emoji"],
            "additionalProperties": false
          },
          {
            "type": "null"
          }
        ]
      }
    },
    "required": [
      "id",
      "url",
      "name",
      "completed",
      "starred",
      "when",
      "reminder",
      "duration",
      "completedAt",
      "updatedAt",
      "source",
      "list"
    ],
    "additionalProperties": false
  }
}

Next: Tools for what an assistant can read and change, or Reminders for setting a time on a task.