> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Calendar Cron & Webhooks — Operational Runbook

> CE-21 Calendar & Scheduling Integration uses three edge functions for OAuth, sync, and free/busy queries.

**Feature ID:** CE-21\
**Created:** 2026-03-31\
**Status:** ✅ Complete

***

## Overview

CE-21 Calendar & Scheduling Integration uses three edge functions for OAuth, sync, and free/busy queries.

## Edge Functions

| Function                  | Purpose                                                    | Trigger                                 |
| ------------------------- | ---------------------------------------------------------- | --------------------------------------- |
| `calendar-oauth-callback` | OAuth code exchange, token encryption, connection creation | User-initiated OAuth redirect           |
| `calendar-sync`           | Two-way event sync (poll or webhook)                       | Cron (configurable interval) or webhook |
| `calendar-freebusy`       | Free/busy availability queries                             | On-demand from UI                       |
| `calendar-schedule`       | Create meeting on external calendar                        | On-demand from ScheduleMeetingDialog    |

## Sync Configuration

Sync poll interval is configured per-organization via `ce_module_settings.calendar_sync_poll_interval_minutes` (default: 15 minutes, range: 5–60).

### Cron Setup

To enable automatic sync polling, create a `pg_cron` job or Supabase Cron that invokes `calendar-sync` at the configured interval:

```sql theme={null}
-- Example: every 15 minutes
SELECT cron.schedule(
  'calendar-sync-poll',
  '*/15 * * * *',
  $$SELECT net.http_post(
    url := current_setting('app.supabase_url') || '/functions/v1/calendar-sync',
    headers := jsonb_build_object(
      'Authorization', 'Bearer ' || current_setting('app.service_role_key'),
      'Content-Type', 'application/json'
    ),
    body := '{"mode":"poll"}'::jsonb
  )$$
);
```

### Webhook Setup (Google/Microsoft)

For real-time sync via push notifications:

1. **Google Calendar:** Configure a watch channel pointing to `{SUPABASE_URL}/functions/v1/calendar-sync`
2. **Microsoft Graph:** Register a subscription for calendar change notifications

## Monitoring

* Edge function logs: Supabase Dashboard → Edge Functions → Logs
* Sync failures: Check `ce_calendar_events.sync_status = 'error'`
* Connection health: Check `ce_calendar_connections.last_sync_at` for stale connections

## Troubleshooting

| Symptom            | Check                                                                      |
| ------------------ | -------------------------------------------------------------------------- |
| Events not syncing | `sync_enabled` on connection; `last_sync_at` timestamp; edge function logs |
| OAuth failure      | Token expiry; refresh token validity; provider API quotas                  |
| Free/busy timeout  | Calendar API rate limits; connection token validity                        |