Event Triggers ^BETA

Description #

Add subscriptions to events to receive notifications based on event transitions, such as a number of minutes before or after an event. Subscriptions are defined through the extra parameters passed to the Create or Update event call.

URL format #

{data_center_url}/v1/calendars/{calendar_id}/events

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-07-27T15:30:00Z",
  "end": "2024-07-27T17:00:00Z",
  "tzid": "America/Chicago",
  "subscriptions": [
    {
      "type": "webhook",
      "uri": "https://example.com/event_trigger/xxxx",
      "transitions": [
        { "before": "event_start", "offset": { "minutes": 5 } }
      ]
    }
  ]
}

Example Response #

HTTP/1.1 202 Accepted

Request parameters #

subscriptions required  #

The array of subscriptions being defined.

subscriptions.type required  #

The String describing what type of subscription is being added. At present, only the value webhook is supported and will call the given URI when triggered.

subscriptions.uri required  #

The URI which will be POSTed to when the subscription is triggered. This can include query parameters if you want to communicate additional fields back to your application.

To be considered successfully delivered:

• Your application must respond in the 2xx range of HTTP status codes.
• Your application must respond within 7 seconds.

subscriptions.transitions required  #

An array of objects defining the transition you want to be notified of.

subscriptions.transitions.before optional  #

Describes a subscription where the notification is delivered before a point in time relative to the event.

Supported values are:

• event_start
• event_end

Either before or after must be given.

subscriptions.transitions.after optional  #

Describes a subscription where the notification is delivered after a point in time relative to the event.

Supported values are:

• event_start
• event_end

Either before or after must be given.

subscriptions.transitions.offset required  #

A duration describing how far the notification delivery window is offset from the point defined by the before or after parameter.

For example:

• { "before": "event_start", "offset": { "hours": 1 } } will trigger 1 hour before the event starts
• { "after": "event_end", "offset": { "minutes": 0 } } will trigger at the end of the event
• { "after": "event_start", "offset": { "minutes": 5 } } will trigger 5 minutes after the event starts

Zero offsets are allowed, but must be explicitly stated, as in the above example. Please note that even with zero offsets, there is a difference between a before or after subscription. Given an event starting at 11:00, with a zero offset:

• A before subscription’s notification would be delivered between 10:59-11:00
• An after subscription’s notification would be delivered between 11:00-11:01

Read more about delivery windows here.

Example Callback #

The callback will contain the event details, as well as some details of the transition that triggered the notification.

POST /event_trigger/xxxx HTTP/1.1
Host: example.com
Content-Type: application/json; charset=utf-8
Cronofy-Notification-ID: 60c210faf5aa93093b000022
Cronofy-Notification-Attempt: 1

{
    "notification": {
        "type": "event_subscription",
        "transitions": [
            {
                "type": "event_start"
            }
        ]
    },
    "event": {
        "calendar_id": "cal_n23kjnwrw2_jsdfjksn234",
        "event_id": "qTtZdczOccgaPncGJaCiLg",
        "event_uid": "evt_partner_60ba0f2968ed0f6e66e1ab68",
        "summary": "Board meeting",
        "description": "Discuss plans for the next quarter",
        "start": "2024-07-27T15:30:00Z",
        "end": "2024-07-27T17:00:00Z",
        "deleted": false,
        "created": "2024-07-27T11:31:53Z",
        "updated": "2024-07-27T11:31:53Z",
        "event_private": false,
        "participation_status": "accepted",
        "attendees": [],
        "organizer": null,
        "transparency": "opaque",
        "status": "confirmed",
        "categories": [],
        "recurring": false,
        "options": {
            "delete": true,
            "update": true,
            "change_participation_status": false
        }
    }
}

Callback headers #

Cronofy-HMAC-SHA256  #

Can optionally be used to verify that the notification was sent by Cronofy.

This HMAC uses the SHA256 algorithm, keyed with the application's client secret, to generate a Base64 encoded hash of the request body.

When an application has multiple active client secrets, a value is generated for each active secret, separated by commas. For example:

 Cronofy-HMAC-SHA256: {HMAC_FROM_SECRET_1},{HMAC_FROM_SECRET_2}
 

Examples are available in our cronofy/notification-hmac-examples Github repository, and our API libraries include methods to verify this header.

Cronofy-Notification-ID  #

An identifier for the notification instance, persistent across retries. Useful for deduplicating any multiple deliveries, which are possible due to our at least once delivery guarantee.

Cronofy-Notification-Attempt  #

The delivery attempt number for the notification, starting at 1. If our first delivery attempt is unsuccessful, we’ll retry multiple times with an incremented value present in this header.

Callback parameters #

notification  #

Details of the subscription that triggered this notification.

event  #

Details of the event for which the notification has been triggered. The fields present map to those documented for our Read Events API.