Calendar V2 Webhooks

Calendar V2 Webhooks

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

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.

🚧

Your Webhook Handlers Should Return a HTTP 2XX Code

If Recall doesn't receive a 2xx response from your system, we will continue to try the message for the next 1 hour (with an increasing delay between attempts).

Setup

Calendar V2 webhooks for a calendar will be sent to the webhook_url specified when you call Create Calendar. If you ever need to update this webhook URL, you can also update this through the API.

Verification

We recommend implementing verification by including a query parameter, such as token=my-secret-token, in the webhook_url you provide.

When we make the request to your endpoint, we will use the exact url, including any query parameters. You will then be able to verify the query parameter in your webhook handler.

For instance, when you create a calendar, you might set the webhook_url to something such as:

JSON

// POST https://api.recall.ai/api/v2/calendars/
{
  "webhook_url": "https://api.myapp.com/webhook/recall/calendar?token=some-token-value",
  ...
}

Then your server can validate the token some-token-value before processing the request, rejecting any requests where the token isn't valid.

This allows you to expose the endpoint publicly while adding a layer of security, since only your server knows the secret token.

Events

---

Calendar Update

This webhook is sent whenever the calendar's data changes (e.g status).

JSON

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

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

Calendar Sync Events

This webhook is sent whenever events on a calendar have been updated.

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. You can choose to do either a full sync or use the last_updated_ts field in the payload (pass as updated_at__gte query parameter) to do an incremental sync of events associated with the calendar on your end.

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, the consumer is expected to filter out events on basis of is_deleted attribute when displaying them to the end user)