---
updatedAt: 2026-10-19T03:59:28.000Z
agentTools:
  projectIndex: https://docs.recall.ai/llms.txt
---

# Calendar V2 Webhooks

Use Calendar V2 webhooks to track calendar and calendar event changes so you can keep bot scheduling in sync through calendar v2

The Calendar V2 API produces two types of webhooks, each scoped to a specific calendar and sent via Svix.

To configure a calendar V2 endpoint, you can follow [this setup guide](https://docs.recall.ai/docs/status-change-webhooks-setup-verification).

These webhooks are used to notify you about changes to calendars and their events, and you should use these to schedule bots and delete them according to your application logic.

# Events

***

## Calendar Update

This webhook is sent whenever the calendar's data changes (for instance, when `status` becomes `disconnected`).

```Text JSON
{
  "event": "calendar.update",
  "data": {
    "calendar_id": string,
  }
}
```

You should re-fetch the calendar via [Retrieve Calendar](https://docs.recall.ai/reference/calendars_retrieve) to get the latest state.

<Callout icon="📘" theme="info">
  ### Disconnects

  A calendar will become disconnected when:

  - You call the Delete Calendar endpoint
  - The refresh token of the user gets revoked, which can happen either:
    - Explicitly removing your installed app
    - The token becomes invalidated

  When this happens, we will send you a `calendar.update` event to notify you of the change.

  In the calendar's `status_changes`, there will be additional details about the disconnection (such as an error code from the Microsoft Graph API).

  _If your Google OAuth client is not approved yet, refresh tokens will&#x20;_[automatically expire after 7 days](https://developers.google.com/identity/protocols/oauth2#expiration)_._
</Callout>

Note that you will not receive a `calendar.update` webhook event if you call the Delete Calendar endpoint as this action is initiated by you.

## Calendar Sync Events

This webhook is sent whenever events on a calendar have been created, updated, or deleted.

```Text JSON
{
  "event": "calendar.sync_events",
  "data": {
    "calendar_id": string,
    "last_updated_ts": string, // iso 8601 formatted datetime
  }
}
```

You should re-fetch the calendar events for this calendar via [List Calendar Events](https://docs.recall.ai/reference/calendar_events_list), while setting the `updated_at__gte` to the `last_updated_ts` value from the webhook to get the changed events. When paginating the calendar events, curl the `next` url returned in the response without modifying the query parameters.

Use the `is_deleted` field on the calendar event object to know if the event has been removed from the calendar or not.

Note: Recall does not *delete* any calendar events, to maintain a system of record. When listing events (for example, to show to users in your UI), you should set the `is_deleted` field to `false`.

# FAQs

## How do I verify Calendar V2 webhooks?

Follow [Verifying Requests from Recall](https://docs.recall.ai/docs/authenticating-requests-from-recallai) to select the correct signing secret and headers for your account and verify incoming requests.

<br />