Push Notifications

Polling for changes is a massively wasteful way of frittering compute cycles. With the of majority systems, the vast majority of the time the results are that nothing has changed. Far better then to only do work when something has changed. That is where push notifications come in.

With the Cronofy API you can set up notifications for each user connected to your application for whenever something changes in their calendar. Adding, updating and deleting of events, whether they are the events your app creates or the user created in their calendar, can all be notified.

How push notifications work

  1. Your app has an HTTP(S) end point on your application to receive push notifications.
  2. Using the Cronofy API you create a Notification Channel for an account with the public url of the end point on your application.
  3. The Cronofy API calls that end point whenever something changes and includes a changes_since time indicating when the changes being alerted relate to.
  4. Your application query the Read Events end point passing the changes_since value as the last_modified parameter.
  5. Your app processes just the events that have changed.

Setting up a notification channel

Push notifications aren’t enabled for Personal Tokens as they have to be linked to an Application, so the first task is to create an Application in the Developer Dashboard. See the Application Authorization tutorial for a full explanation of Applications and obtaining authorization to access a user’s calendars.

Once you have an application, create a Notification Channel. There are no restrictions on the URL here so you can have an individual URL for each user in your application.

https://yourapp.com/cronofy/channel/{your user id}
https://yourapp.com/cronofy?user_id={your user id}

Whatever suits your application.

Receiving notifications

Your endpoint will receive something similar to the following when any calendar changes are detected.

POST {CALLBACK_URL_PATH} HTTP/1.1
Host: {CALLBACK_URL_HOST}
Content-Type: application/json; charset=utf-8

{
  "notification": {
    "type": "change",
    "changes_since": "2016-03-01T09:24:16Z"
  },
  "channel": {
    "channel_id": "chn_54cf7c7cb4ad4c1027000001",
    "callback_url": {CALLBACK_URL},
    "filters": {}
  }
}

Your app can then query the Read Events endpoint to get the latest changes using the changes_since value as the last_modified parameter.

As long as your application responds with an HTTP status code in the 2xx range within 5 seconds, the Cronofy API will consider the push notification successful.

If it takes longer than 5 seconds to respond, or responds with a code not in the 2xx range will be treated as if it has failed.
We will continue to attempt to send the push notification for 24 hours. If no notifications succeed during this period then it is assumed that the channel is no longer valid and so the channel will be closed automatically and no further push notifications will be sent.

This is the point where queuing received notifications for later processing can be really advantageous.

Testing locally

Ngrok is your friend when it comes to testing your push notification endpoint. This downloadable software allows you to expose a local server behind a NAT or firewall to the internet.

First step once you’ve download is to set up the tunnel to your local application. For example this would set up an http tunnel to the default rails server port on your local machine.

ngrok http localhost:3000

You’ll be shown a console with the details of the public URL. For instance in this example you can use https://0c2ada98.ngrok.io as the root url for your channels.

ngrok

Then create channel for your account with that URL and the path to your web hook and you can test against Cronofy API live but on your local machine.

Another awesome feature of ngrok is the web console that allows you to inspect traffic and replay if necessary. You’ll find it at http://127.0.0.1:4040.

For more advanced options it’s worth reading the ngrok docs.

What next?

Take a look at the Push Notifications section of the Cronofy API docs for more detailed implementation information.

Otherwise, try it and if you have any questions please don’t hesitate to drop us a line at support@cronofy.com.