Calendar Webhooks for AI Agents: Reconcile Without Duplicate Bookings

Build the calendar reconciliation loop in eight steps

Keep provider change tracking below the meeting workflow. The provider layer determines what calendar evidence changed. The meeting layer determines which proposals, approvals, outreach tasks, or bookings that change can affect.

1. 1

   Give every meeting and availability read a stable identity

   Start with a typed meeting record: request ID, revision, organizer, purpose, duration, date window, deadline, IANA time zone, required people, optional people, outreach authority, consent, and approval policy. Give each calendar connection, subscription, participant, availability snapshot, proposal, and booking attempt its own stable ID.
   • A provider event ID never substitutes for the meeting request ID.
   • Every proposal records the exact availability evidence version it used.
   • Required and optional attendance remain explicit after every change.
2. 2

   Register provider subscriptions as expiring resources

   Google Calendar push channels are created for a watched resource and carry channel and resource identifiers. Microsoft Graph subscriptions have a resource and expiration. Store provider, account, resource, subscription ID, verification material, created time, expiration, renewal status, and the meeting windows that depend on that connection.
   • Renew before expiration and alert when renewal fails.
   • Stop old channels or subscriptions when credentials or scope change.
   • Map every notification to an authorized connection before processing it.
3. 3

   Acknowledge quickly and queue the real work

   Verify the provider-specific request, persist a delivery fingerprint, acknowledge inside the provider’s expected window, and enqueue reconciliation. Do not read five calendars, call the model, send participant messages, or create an event inside the webhook request. A retrying provider should see the same accepted result for the same delivery.
   • Reject notifications that cannot be mapped to a live subscription.
   • Keep request verification secrets out of logs and model context.
   • Queue by connection and calendar so bursts do not race the same sync cursor.
4. 4

   Deduplicate delivery without discarding real changes

   Store provider, subscription or channel ID, resource ID, provider sequence data when present, received time, and a payload hash. Use that record to make receipt idempotent. Deduplicating transport is different from deduplicating a calendar change: two notifications may point to the same current provider state, while one notification may represent several changes.
   • A duplicate delivery cannot send a second reminder or booking command.
   • Out-of-order deliveries still trigger comparison against current state.
   • Keep a bounded retention window long enough to cover provider retries.
5. 5

   Run incremental sync and recover an invalid cursor

   For Google, persist the next sync token after a complete paginated sync; a 410 response requires a fresh full sync. For Microsoft, track each calendar view and its delta link independently. A notification tells the worker to reconcile. The incremental cursor determines which provider records changed since the last completed checkpoint.
   • Commit a new cursor only after every page is processed.
   • Rebuild the bounded meeting window after an invalid or expired cursor.
   • Treat deleted and moved events as availability changes, not missing data.
6. 6

   Invalidate only the meeting evidence the change can affect

   Map changed busy intervals to active meeting windows and participants. Mark affected availability snapshots stale, expire proposals that depend on them, and wake only those meeting jobs. Keep connected free/busy separate from conversational availability; a calendar change does not erase an unconnected participant’s explicit reply, though its freshness policy may still expire it.
   • A changed optional calendar can alter ranking without erasing required overlap.
   • A changed required calendar invalidates approval for any conflicting proposal.
   • A change outside the meeting window does not restart unrelated coordination.
7. 7

   Re-check required free/busy at the commit boundary

   Webhook pipelines can lag, subscriptions can expire, and notifications can arrive out of order. Before creating the event, query current approved free/busy for every connected required participant and combine it with fresh conversational evidence for unconnected required people. If the evidence version changed, stop the commit and regenerate proposals.
   • No usable provider response is never treated as free time.
   • Ambiguous conversational availability returns to participant clarification.
   • The final check uses the approved meeting revision and exact attendee set.
8. 8

   Commit once, verify, and keep a repair path

   Derive a booking idempotency key from meeting request, revision, and approved proposal. Persist the provider event ID before reporting success. If the write times out, query or reconcile by that key and organizer calendar before retrying. Verify start, end, time zone, required attendees, optional attendees, and invitation dispatch, then expose a repair state if any part differs.
   • A replayed webhook cannot create another event.
   • A reschedule creates a new revision while preserving the original meeting identity.
   • Traces connect notification, sync cursor, evidence invalidation, approval, and booking result.

Compare change handling by meeting outcome

Fast notification is useful. Safe scheduling depends on what happens between that signal and the final invitation.