Remove unused webhook_offsets field from calendars

webhook_offsets was a placeholder for pre-event reminder webhooks that
was never implemented. Remove it from the schema, API handlers, docs,
and specs to avoid shipping an unused field that causes confusion.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: plc

CALDAVE_SPEC.md

@@ -352,12 +352,11 @@ Create a new calendar for the authenticated agent.
   "timezone": "America/Denver",
   "webhook_url": "https://example.com/webhook",
   "webhook_secret": "my_secret",
-  "webhook_offsets": [300, 900],
   "welcome_event": false
 }
 ```
 
-Optional fields: `timezone` (default UTC), `webhook_url`, `webhook_secret`, `webhook_offsets`, `agentmail_api_key`, `welcome_event` (default true — set to false to skip the auto-created welcome event).
+Optional fields: `timezone` (default UTC), `webhook_url`, `webhook_secret`, `agentmail_api_key`, `welcome_event` (default true — set to false to skip the auto-created welcome event).
 
 **Response:**
 ```json
@@ -475,8 +474,7 @@ Set or update webhook configuration:
 ```json
 {
   "webhook_url": "https://my-agent.fly.dev/hooks/calendar",
-  "webhook_secret": "whsec_...",
-  "webhook_offsets": ["-5m", "-1m", "0"]
+  "webhook_secret": "whsec_..."
 }
 ```
 
@@ -697,7 +695,6 @@ For local development or offline use, run the STDIO server directly:
 | `feed_token` | `text` | Token for iCal feed auth |
 | `webhook_url` | `text` | Nullable |
 | `webhook_secret` | `text` | Nullable |
-| `webhook_offsets` | `jsonb` | Default `["-5m"]` |
 | `inbound_token` | `text` UNIQUE | `inb_` prefixed, for per-calendar webhook URL |
 | `agentmail_api_key` | `text` | Nullable, for fetching AgentMail attachments |
 | `created_at` | `timestamptz` | |

CHANGELOG.md

@@ -21,7 +21,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
   - **Event tools**: `caldave_get_event`, `caldave_view_calendar`
   - **Debugging**: `caldave_list_errors`, `caldave_get_error`
   - **Discovery**: `caldave_get_changelog`, `caldave_get_manual`
-- **Missing parameters on existing MCP tools** — `caldave_create_event` now supports `metadata`, `attendees`, and `status`. `caldave_update_event` now supports `metadata`, `attendees`, and `recurrence`. `caldave_create_calendar` now supports `webhook_url`, `webhook_secret`, `webhook_offsets`, `agentmail_api_key`, and `welcome_event`.
+- **Missing parameters on existing MCP tools** — `caldave_create_event` now supports `metadata`, `attendees`, and `status`. `caldave_update_event` now supports `metadata`, `attendees`, and `recurrence`. `caldave_create_calendar` now supports `webhook_url`, `webhook_secret`, `agentmail_api_key`, and `welcome_event`.
 - **Remote MCP endpoint at `/mcp`** — CalDave now serves an MCP endpoint via Streamable HTTP transport. Agents can connect with just a URL and API key (`{ "url": "https://caldave.ai/mcp", "headers": { "Authorization": "Bearer sk_live_..." } }`) — no local installation required. Sessions are stateful with automatic 30-minute TTL cleanup.
 - **MCP agent guide** — Enhanced MCP instructions with structured quick-start, workflow descriptions, and tool selection guide. Added `caldave://guide` MCP resource with a comprehensive getting-started guide for agents (setup checklist, code examples, event fields reference, webhook/SMTP config, debugging).
 
@@ -45,7 +45,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - **SMTP test `to` parameter** — `POST /agents/smtp/test` now accepts an optional `to` body parameter to send the test email to a specific address instead of the configured `from` address.
 - **SMTP test endpoint** — `POST /agents/smtp/test` sends a test email to verify your SMTP configuration works. Sends to the configured `from` address and reports success/failure with the SMTP error message if any.
 - **SMTP `secure` field** — `PUT /agents/smtp` now accepts an optional `secure` boolean to explicitly control TLS mode. Use `true` for implicit TLS (port 465) or `false` for STARTTLS (port 587). Auto-detected from port when omitted.
-- **Webhook config at calendar creation** — `POST /calendars` now accepts `webhook_url`, `webhook_secret`, and `webhook_offsets` at creation time, saving a separate `PATCH` call.
+- **Webhook config at calendar creation** — `POST /calendars` now accepts `webhook_url` and `webhook_secret` at creation time, saving a separate `PATCH` call.
 - **`email_sent` in event responses** — `POST` and `PATCH` event endpoints now return `email_sent: true/false` when the event has attendees, confirming whether the invite was dispatched. Invites are now sent synchronously before the response is returned.
 - **SMTP integration for outbound emails** — configure your own SMTP server via `PUT /agents/smtp` so calendar invites and RSVP replies are sent from your email address instead of CalDave's built-in delivery. New `GET /agents/smtp` (view config, password excluded) and `DELETE /agents/smtp` (revert to built-in). `GET /agents/me` now includes `smtp_configured` boolean. Supports any SMTP provider (AgentMail, SendGrid, Gmail, etc.).
 - **Webhook test endpoint** — `POST /calendars/:id/webhook/test` sends a test payload to the calendar's configured webhook URL and returns the HTTP status code. Supports HMAC-SHA256 signing via `X-CalDave-Signature` when `webhook_secret` is set.

src/db.js

@@ -41,7 +41,6 @@ async function initSchema() {
       feed_token      text,
       webhook_url     text,
       webhook_secret  text,
-      webhook_offsets jsonb DEFAULT '[\"-5m\"]',
       inbound_token   text UNIQUE,
       created_at      timestamptz NOT NULL DEFAULT now()
     );

src/lib/mcp-tools.mjs

@@ -53,8 +53,7 @@ const INSTRUCTIONS = [
   '',
   'Webhooks',
   '--------',
-  'Set webhook_url on a calendar to get notified before events start.',
-  'Use webhook_offsets (e.g. ["-5m", "-15m"]) for advance reminders.',
+  'Set webhook_url on a calendar to get notified when events change.',
   'Test with caldave_test_webhook before relying on it.',
   '',
   'Choosing the right tool',
@@ -178,8 +177,7 @@ export function registerTools(server, callApi, baseUrl, apiKey) {
           '## Webhook notifications',
           '',
           'Set `webhook_url` when creating/updating a calendar. CalDave sends a POST',
-          'request before events start. Configure `webhook_offsets` to control timing',
-          '(e.g. `["-5m", "-15m"]` for 5 and 15 minutes before).',
+          'to your URL whenever events are created, updated, deleted, or responded to.',
           '',
           'If you set a `webhook_secret`, verify the `X-CalDave-Signature` header',
           'using HMAC-SHA256 on the raw request body.',
@@ -335,16 +333,14 @@ export function registerTools(server, callApi, baseUrl, apiKey) {
       timezone: z.string().optional().describe('IANA timezone (default: UTC)'),
       webhook_url: z.string().optional().describe('URL to receive event webhooks'),
       webhook_secret: z.string().optional().describe('Secret for HMAC-SHA256 webhook signatures'),
-      webhook_offsets: z.array(z.union([z.number(), z.string()])).optional().describe('Offsets for pre-event webhook reminders (e.g. [300, 900] or ["-5m", "-1m"])'),
       agentmail_api_key: z.string().optional().describe('AgentMail API key for inbound email attachments'),
       welcome_event: z.boolean().optional().describe('Set to false to skip the auto-created welcome event (default: true)'),
     },
-    async ({ name, timezone, webhook_url, webhook_secret, webhook_offsets, agentmail_api_key, welcome_event }) => {
+    async ({ name, timezone, webhook_url, webhook_secret, agentmail_api_key, welcome_event }) => {
       const body = { name };
       if (timezone) body.timezone = timezone;
       if (webhook_url) body.webhook_url = webhook_url;
       if (webhook_secret) body.webhook_secret = webhook_secret;
-      if (webhook_offsets) body.webhook_offsets = webhook_offsets;
       if (agentmail_api_key) body.agentmail_api_key = agentmail_api_key;
       if (welcome_event !== undefined) body.welcome_event = welcome_event;
       const data = await callApi('POST', '/calendars', body);
@@ -361,16 +357,14 @@ export function registerTools(server, callApi, baseUrl, apiKey) {
       timezone: z.string().optional().describe('IANA timezone'),
       webhook_url: z.string().optional().describe('URL to receive event notifications'),
       webhook_secret: z.string().optional().describe('HMAC secret for webhook signatures'),
-      webhook_offsets: z.array(z.union([z.number(), z.string()])).optional().describe('Reminder offsets, e.g. ["-5m", "-1m"]'),
       agentmail_api_key: z.string().optional().describe('AgentMail API key'),
     },
-    async ({ calendar_id, name, timezone, webhook_url, webhook_secret, webhook_offsets, agentmail_api_key }) => {
+    async ({ calendar_id, name, timezone, webhook_url, webhook_secret, agentmail_api_key }) => {
       const body = {};
       if (name !== undefined) body.name = name;
       if (timezone !== undefined) body.timezone = timezone;
       if (webhook_url !== undefined) body.webhook_url = webhook_url;
       if (webhook_secret !== undefined) body.webhook_secret = webhook_secret;
-      if (webhook_offsets !== undefined) body.webhook_offsets = webhook_offsets;
       if (agentmail_api_key !== undefined) body.agentmail_api_key = agentmail_api_key;
       const data = await callApi('PATCH', `/calendars/${calendar_id}`, body);
       return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };

src/routes/calendars.js

@@ -54,9 +54,9 @@ function formatCalendar(cal) {
   };
 }
 
-const KNOWN_CALENDAR_POST_FIELDS = new Set(['name', 'timezone', 'agentmail_api_key', 'welcome_event', 'webhook_url', 'webhook_secret', 'webhook_offsets']);
+const KNOWN_CALENDAR_POST_FIELDS = new Set(['name', 'timezone', 'agentmail_api_key', 'welcome_event', 'webhook_url', 'webhook_secret']);
 const KNOWN_CALENDAR_PATCH_FIELDS = new Set([
-  'name', 'timezone', 'webhook_url', 'webhook_secret', 'webhook_offsets', 'agentmail_api_key',
+  'name', 'timezone', 'webhook_url', 'webhook_secret', 'agentmail_api_key',
 ]);
 
 function checkUnknownFields(body, knownFields) {
@@ -74,7 +74,7 @@ router.post('/', async (req, res) => {
     const unknownErr = checkUnknownFields(req.body, KNOWN_CALENDAR_POST_FIELDS);
     if (unknownErr) return res.status(400).json({ error: unknownErr });
 
-    const { name, timezone, agentmail_api_key, welcome_event, webhook_url, webhook_secret, webhook_offsets } = req.body;
+    const { name, timezone, agentmail_api_key, welcome_event, webhook_url, webhook_secret } = req.body;
 
     if (!name) {
       return res.status(400).json({ error: 'name is required' });
@@ -98,9 +98,9 @@ router.post('/', async (req, res) => {
     const tz = timezone || 'UTC';
 
     await pool.query(
-      `INSERT INTO calendars (id, agent_id, name, timezone, email, feed_token, inbound_token, agentmail_api_key, webhook_url, webhook_secret, webhook_offsets)
-       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)`,
-      [id, req.agent.id, name, tz, email, token, inbToken, agentmail_api_key || null, webhook_url || null, webhook_secret || null, webhook_offsets ? JSON.stringify(webhook_offsets) : null]
+      `INSERT INTO calendars (id, agent_id, name, timezone, email, feed_token, inbound_token, agentmail_api_key, webhook_url, webhook_secret)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)`,
+      [id, req.agent.id, name, tz, email, token, inbToken, agentmail_api_key || null, webhook_url || null, webhook_secret || null]
     );
 
     // Create welcome event unless explicitly opted out
@@ -188,7 +188,7 @@ router.patch('/:id', async (req, res) => {
     const unknownErr = checkUnknownFields(req.body, KNOWN_CALENDAR_PATCH_FIELDS);
     if (unknownErr) return res.status(400).json({ error: unknownErr });
 
-    const { name, timezone, webhook_url, webhook_secret, webhook_offsets, agentmail_api_key } = req.body;
+    const { name, timezone, webhook_url, webhook_secret, agentmail_api_key } = req.body;
 
     // Input validation
     if (name !== undefined && name.length > 255) {
@@ -212,7 +212,6 @@ router.patch('/:id', async (req, res) => {
     if (timezone !== undefined) { updates.push(`timezone = $${idx++}`); values.push(timezone); }
     if (webhook_url !== undefined) { updates.push(`webhook_url = $${idx++}`); values.push(webhook_url); }
     if (webhook_secret !== undefined) { updates.push(`webhook_secret = $${idx++}`); values.push(webhook_secret); }
-    if (webhook_offsets !== undefined) { updates.push(`webhook_offsets = $${idx++}`); values.push(JSON.stringify(webhook_offsets)); }
     if (agentmail_api_key !== undefined) { updates.push(`agentmail_api_key = $${idx++}`); values.push(agentmail_api_key); }
 
     if (updates.length === 0) {

src/routes/changelog.js

@@ -253,7 +253,7 @@ const CHANGELOG = [
       {
         type: 'feature',
         title: 'Webhook config at calendar creation',
-        description: 'POST /calendars now accepts webhook_url, webhook_secret, and webhook_offsets so you can configure webhooks in a single call instead of a separate PATCH.',
+        description: 'POST /calendars now accepts webhook_url and webhook_secret so you can configure webhooks in a single call instead of a separate PATCH.',
         endpoints: ['POST /calendars'],
         docs: BASE + '/docs#post-calendars',
       },

src/routes/docs.js

@@ -399,7 +399,6 @@ const cachedHtml = `<!DOCTYPE html>
         <div class="param"><span class="param-name">agentmail_api_key <span class="param-opt">optional</span></span><span class="param-desc">AgentMail API key for fetching inbound email attachments</span></div>
         <div class="param"><span class="param-name">webhook_url <span class="param-opt">optional</span></span><span class="param-desc">URL to receive event webhooks (must be a valid URL)</span></div>
         <div class="param"><span class="param-name">webhook_secret <span class="param-opt">optional</span></span><span class="param-desc">Secret for HMAC-SHA256 webhook signatures (sent in <code class="inline-code">X-CalDave-Signature</code> header)</span></div>
-        <div class="param"><span class="param-name">webhook_offsets <span class="param-opt">optional</span></span><span class="param-desc">Reserved for future pre-event reminders. Stored but not yet acted on.</span></div>
         <div class="param"><span class="param-name">welcome_event <span class="param-opt">optional</span></span><span class="param-desc">Set to <code class="inline-code">false</code> to skip the auto-created welcome event (recommended for production agents). Defaults to true.</span></div>
       </div>
       <div class="label">Example</div>
@@ -457,7 +456,6 @@ const cachedHtml = `<!DOCTYPE html>
         <div class="param"><span class="param-name">timezone</span><span class="param-desc">IANA timezone</span></div>
         <div class="param"><span class="param-name">webhook_url</span><span class="param-desc">URL to receive event notifications</span></div>
         <div class="param"><span class="param-name">webhook_secret</span><span class="param-desc">HMAC secret for webhook signatures</span></div>
-        <div class="param"><span class="param-name">webhook_offsets</span><span class="param-desc">Reserved for future pre-event reminders</span></div>
         <div class="param"><span class="param-name">agentmail_api_key</span><span class="param-desc">AgentMail API key for this calendar</span></div>
       </div>
       <div class="label">Example</div>

src/routes/man.js

@@ -241,7 +241,6 @@ function getEndpoints() {
         { name: 'agentmail_api_key', in: 'body', required: false, type: 'string', description: 'AgentMail API key for inbound email attachments' },
         { name: 'webhook_url', in: 'body', required: false, type: 'string', description: 'URL to receive event webhooks' },
         { name: 'webhook_secret', in: 'body', required: false, type: 'string', description: 'Secret for HMAC-SHA256 webhook signatures' },
-        { name: 'webhook_offsets', in: 'body', required: false, type: 'array', description: 'Reserved for future pre-event reminders. Stored but not yet acted on.' },
         { name: 'welcome_event', in: 'body', required: false, type: 'boolean', description: 'Set to false to skip the auto-created welcome event (recommended for production). Defaults to true.' },
       ],
       example_body: { name: 'Work Schedule', timezone: 'America/Denver' },
@@ -288,7 +287,6 @@ function getEndpoints() {
         { name: 'timezone', in: 'body', required: false, type: 'string', description: 'IANA timezone' },
         { name: 'webhook_url', in: 'body', required: false, type: 'string', description: 'URL to receive event notifications' },
         { name: 'webhook_secret', in: 'body', required: false, type: 'string', description: 'HMAC secret for webhook signatures' },
-        { name: 'webhook_offsets', in: 'body', required: false, type: 'array', description: 'Reserved for future pre-event reminders. Stored but not yet acted on.' },
         { name: 'agentmail_api_key', in: 'body', required: false, type: 'string', description: 'AgentMail API key' },
       ],
       example_body: { name: 'Updated Name', timezone: 'America/New_York' },