Create Notification Channel

Description #

Creates a new channel for receiving notifications when changes occur.

Notification channels can be created with additional filters which can be thought of as a subset of those available when reading events.

Each account has a limit of 128 channels, though we recommend only using one.

URL format #

{data_center_url}/v1/channels

Example Request #

POST /v1/channels HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "callback_url": {CALLBACK_URL},
  "filters": {
    "calendar_ids": [ "cal_n23kjnwrw2_sakdnawerd3" ],
    "only_managed": false
  }
}

Example Response #

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "channel": {
    "channel_id": "chn_54cf7c7cb4ad4c1027000001",
    "callback_url": {CALLBACK_URL},
    "filters": {
      "calendar_ids": [ "cal_n23kjnwrw2_sakdnawerd3" ],
      "only_managed": false
    }
  }
}

Request parameters #

callback_url required  #

The HTTP or HTTPS URL you wish to receive push notifications. HTTPS is strongly preferred.

filters.calendar_ids optional  #

Restricts the notifications to changes to events within the specified calendars.

The possible calendar_ids can be discovered through the list calendars endpoint.

If omitted, notifications are sent for changes to events across all calendars. When specified, at least one calendar_id must be provided.

filters.only_managed optional  #

A Boolean specifying whether only events that you are managing for the account should trigger notifications.

By default all events trigger notifications, both those created by the user and those you are managing.

Response parameters #

channel.channel_id  #

The ID of the channel.

Note that ID may be for an existing channel if you make a request to create a channel that is identical to an existing one.

channel.callback_url  #

The URL that will receive push notification requests.

channel.filters  #

Any non-default filters that were specified for the channel.

Error responses #

401 Unauthorized #

The request was refused as the provided authentication credentials were not recognized.

When an OAuth refresh_token is available then it should be used to request a replacement auth_token before the request is retried.

422 Unprocessable #

The request was unable to be processed due to it containing invalid parameters.

The response will contain a JSON object containing one or more errors relating to the invalid parameters.

For example, if you omitted the required callback_url parameter, you would receive a response like:

{
  "errors": {
    "callback_url": [
      {
        "key": "errors.required",
        "description": "required"
      }
    ]
  }
}

The key field is intended for programmatic use and the description field is a human-readable equivalent.