Push Notifications

Description #

Conferencing details are assigned to events asynchronously and in certain workflows it is desirable to know that has been completed and what the details are, or respond to an error.

Cronofy will attempt to generate and write a conference on the initial write of the event. However, in cases where the conferencing generation fails for an unforeseen reason, the event is written to the calendar in order to hold the time for the attendees and keep their availability accurate.

Push Notifications can be subscribed to so that your application can be updated when a conference has been generated or an event has been written without conferencing.

This is an extension to the Upsert Event API payload, where a subscriptions object is added to the event to with an interactions array containing the interactions you are interested in. See interaction types below.

Example Request #

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

{
  "event_id": "qTtZdczOccgaPncGJaCiLg",
  "summary": "Board meeting",
  "description": "Discuss plans for the next quarter.",
  "start": "2024-05-15T15:30:00Z",
  "end": "2024-05-15T17:00:00Z",
  "conferencing": {
    "profile_id": "default"
  },
  "subscriptions": [
    {
      "type": "webhook",
      "uri": "https://example.com/notification",
      "interactions": [
        {
          "type": "conferencing_assigned"
        },
        {
          "type": "conferencing_failing"
        }
      ]
    }
  ]
}

Parameters #

subscriptions optional  #

Object containing an array of subscriptions.

subscriptions[].type optional  #

Only one value of webhook is supported.

subscriptions[].uri optional  #

The URI within your application you want Cronofy to send notifications to when the interaction is triggered. Must be an externally accessible HTTP or HTTPS URI.

subscriptions[].interactions optional  #

An array of interactions that should trigger a call to the uri.

subscriptions[].interactions[].type optional  #

The type of interaction. Currently supported are:

• conferencing_assigned - sent when conferencing details are successfully generated for an event. The event will have been given a conferencing.join_url value at this point.
• conferencing_failing - sent when errors from the conferencing service are preventing conferencing details from being assigned (e.g. the API for a conferencing provider is down or the users credentials have expired). In this situation, the event is added or updated in the target calendar without conferencing while conferencing creation is retried periodically. If conferencing is successfully created, the event will be updated with the conference details and a conferencing_assigned notification will be sent as normal.

Example Callbacks #

conferencing_assigned

POST /notification HTTP/1.1
Host: example.com
Content-Type: application/json; charset=utf-8
Cronofy-HMAC-SHA256: {Base64(HmacSHA256(body_bytes, CLIENT_SECRET))}

{
  "notification": {
    "type": "event_subscription",
    "interactions": [
      {
        "type": "conferencing_assigned"
      }
    ]
  },
  "event": {
    "event_id": "qTtZdczOccgaPncGJaCiLg",
    "summary": "Board meeting",
    "description": "Discuss plans for the next quarter.",
    "start": "2024-05-15T15:30:00Z",
    "end": "2024-05-15T17:00:00Z",
    "conferencing": {
      "provider_name": "zoom",
      "join_url": "https://zoom.us/00001111-222"
    }
  }
}

conferencing_failing

POST /notification HTTP/1.1
Host: example.com
Content-Type: application/json; charset=utf-8
Cronofy-HMAC-SHA256: {Base64(HmacSHA256(body_bytes, CLIENT_SECRET))}

{
  "notification": {
    "type": "event_subscription",
    "interactions": [
      {
        "type": "conferencing_failing",
        "subtype": "profile_missing"
      }
    ]
  },
  "event": {
    "event_id": "qTtZdczOccgaPncGJaCiLg",
    "summary": "Board meeting",
    "description": "Discuss plans for the next quarter.",
    "start": "2024-05-15T15:30:00Z",
    "end": "2024-05-15T17:00:00Z"
  }
}

Response parameters #

notification.interactions.type required  #

Denotes the type of notification which has fired.

notification.interactions.subtype optional  #

Additional context for the reason the Push Notification has fired. There is currently one value:

• profile_missing - The conferencing profile specified has been removed between the API call and the attempt to generate the conference. The event will be created without conferencing, but a new conferencing profile_id should be set via the Update Event end point.

event required  #

The details of the event which has been updated.

event.conferencing required  #

Prior to conference generation, this key will be set to { "pending": true }

After successful conference generation, this is set to an object containing details of the conference. More can be read about these values on the Create or Update Event page.