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.

URL format #

api.cronofy.com/v1/channels

Example Request #

POST /v1/channels HTTP/1.1
Host: api.cronofy.com
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.

Must not be longer than 128 characters and should be HTTPS.

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.

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.

Search