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.

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).

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

You should re-fetch the calendar via Retrieve Calendar to get the latest state.

📘

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 (for example, due to a user changing their password)

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 willautomatically expire after 7 days.

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.

{
  "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, while setting the updated_at__gte to the last_updated_ts value from the webhook to get the changed events.

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.