---
title: "Subscribe to events (MCP Events)"
method: POST
path: "/v1/webhooks/subscribe"
tags: ["Webhook"]
---

# Subscribe to events (MCP Events)

`POST /v1/webhooks/subscribe`

## Request

- Base URL: `https://api.timesheet.io`
- URL: `https://api.timesheet.io/v1/webhooks/subscribe`
- Auth: one of:
  - HTTP bearer
  - API key in header `Authorization`

Creates or refreshes an MCP Events webhook subscription, as the Timesheet MCP server forwards events/subscribe. A subscription is identified by the event, its arguments and the callback URL: the same request again refreshes it and replaces its secret. The callback has to answer a signed verification challenge before the first delivery. Deliveries use Standard Webhooks signatures with the secret the caller supplied, and the subscription lapses at refreshBefore unless refreshed.

## Request body

- WebhookSubscribeDto
  - `name` string
  - `arguments` object
  - `url` string
  - `secret` string
  - `ttlMs` integer

## Response `200`

Subscription created or refreshed

- WebhookSubscribeResponse
  - `id` string
  - `refreshBefore` string

## Other responses

- `400`: Unknown event, arguments given, or an invalid callback URL or secret
- `401`: Not authorized
- `402`: The plan does not include webhooks
- `422`: type CallbackEndpointError: the callback failed verification (message is the reason category); type ResourceExhausted: too many subscriptions

## Changes

> 14 revisions in range; 1 not diffed.

- **2026-10-21** `b612f5a81b8a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/timesheet/apis/timesheet-api/changes/v1/webhooks/subscribe/post.md)

---

[API](https://skmtc.dev/timesheet/apis/timesheet-api.md) - [All operations](https://skmtc.dev/timesheet/apis/timesheet-api/llms.txt) - [OpenAPI document](https://skmtc.dev/timesheet/apis/timesheet-api/revisions/2f6595c95dc4?raw)