Push Notifications

Required plan: Starter

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.

sequenceDiagram autonumber Your Application->>Cronofy: Create event with conferencing Cronofy->>Conferencing provider: Create conference alt Conference generation works Conferencing provider->>Cronofy: Conference details Cronofy->>Calendar provider: Write event with conference Cronofy-->>Your Application: conferencing_success else Conference generation fails Conferencing provider->>Cronofy: Error Cronofy->>Calendar provider: Write event without conference Cronofy-->>Your Application: conferencing_failing Cronofy->>Conferencing provider: Retry create conference end

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": "2022-11-30T15:30:00Z",
  "end": "2022-11-30T17:00:00Z",
  "conferencing": {
    "profile_id": "default"
  },
  "subscriptions": [
    {
      "type": "webhook",
      "uri": "https://example.com/notification",
      "interactions": [
        {
          "type": "conferencing_assigned"
        },
        {
          "type": "conferencing_failing"
        }
      ]
    }
  ]
}

Parameters #

data_center_url required

The URL for the data center you want to communicate with. Possible choices are:

  • api-au.cronofy.com - πŸ‡¦πŸ‡Ί Australia
  • api-ca.cronofy.com - πŸ‡¨πŸ‡¦ Canada
  • api-de.cronofy.com - πŸ‡©πŸ‡ͺ Germany
  • api-sg.cronofy.com - πŸ‡ΈπŸ‡¬ Singapore
  • api-uk.cronofy.com - πŸ‡¬πŸ‡§ United Kingdom
  • api.cronofy.com - πŸ‡ΊπŸ‡Έ United States

Find out more about Cronofy's data centers.

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 Callback #

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": "2022-11-30T15:30:00Z",
    "end": "2022-11-30T17:00:00Z",
    "conferencing": {
      "provider_name": "zoom",
      "join_url": "https://zoom.us/00001111-222"
    }
  }
}

Respsonse 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]/developers/api/events/upsert-event/ API.
event required  #

The details of the event which has been updated.

event.conferencing required  #
The state of conferencing on the event.

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.