Event Triggers ^BETA

Event Triggers are a powerful feature for driving application workflows. It allows your application to register a webhook to be called at a time relative to the start and/or end of a calendar event.

This works by your application setting up subscriptions to one or more transitions. In the abridged event creation example below, the URL https://yourapp.com/event_trigger/xxxx will receive a callback 5 minutes before the event starts and 10 minutes after the event ends.

{
  "event_id": "workflow-example",
  ...
  "subscriptions": [
    {
      "type": "webhook",
      "uri": "https://yourapp.com/event_trigger/xxxx",
      "transitions": [
        { "before": "event_start", "offset": { "minutes": 5 } },
        { "after": "event_end", "offset": { "minutes": 10 } }
      ]
    }
  ]
}

Setting up triggers for specific events #

Event Triggers are an addition to our Create or Update Event API payload. Please see the full API documentation for this feature here.

FAQs #

Do I need to reschedule subscriptions if events move or change duration? #

No. Cronofy’s sync engine tracks the movement of calendar events, whether via the API, or by the event being moved in the calendar itself by end-users. Your subscriptions are defined relative to event start or end times. Once the subscription is added to the event, its delivery time will be kept up-to-date with the state of the event.

When is the notification delivered? #

Notifications based on the event start/end times naturally lead to spikes in activity at particular times. Calendar events tend to be scheduled at the 15 minute offsets, and particularly at the top of the hour. It’s rare to see a calendar event starting at 11:07, for example. To ensure consistent performance and to smooth the impact upon your application, we deliver notifications within a 1 minute window relative to the target time.

This only applies to the first attempt at delivery - if your application is unreachable, slow to respond, or does not reply with a HTTP 2xx status, the notification will be retried several times but these may fall outside of the 1 minute window.

The 1 minute window is based on the transition time (event start or event end) and the offset you specify.

The window is set to the side of the transition time furthest from the event- before subscriptions will be triggered up to 1 minute before the target time, and after subscriptions will be triggered up to 1 minute after the target time.

For example, given an event occurring from 10:00 to 10:30:

How many messages will I receive for a single subscription? #

For a given notification, we guarantee at least once delivery to your application unless delivery fails for a prolonged period. While we do everything we can to limit this to a single message, the nature of distributed systems means that a single notification cannot be guaranteed. It is unlikely to be duplicated but you should account for this in your integration. Notification payloads contain a Cronofy-Notification-ID HTTP header, which can be used to deduplicate, if your operation is not idempotent.

If an event moves, a new notification will be scheduled, even if one was already sent for the same event.

What happens if I create an event or move it such that some subscriptions are now in the past? #

It is entirely possible to schedule triggers in the past. For example, we could create an event to start in 1 hour, and add a subscription to be notified 2 hours before the start of the event. In these cases, Cronofy will dispatch this notification immediately so that your workflow is still triggered.

For this reason, your workflow might need to consider the start_time of the event before processing the notification. For example, a reminder email for an interview event would still be useful, but it may be too late for a workflow integration which calls a catering company’s API to order sandwiches.

Overdue notifications can also happen because an event is moved. When event start or end times changed, any notifications for the event will be re-queued for the new times. This means that if an event starting in 2 hours with a trigger for 30 minutes before the start of the event is moved to start in 15 minutes from now, the before trigger will immediately send a notification. This is because the event start has changed and the notification is now “overdue”, so Cronofy will immediately dispatch it.