Scheduler v2 webhooks
Scheduler webhooks allow you to build custom logic into your application for upcoming bookings. Setting webhooks up helps to keep track of event changes through calendars and then update corresponding bookings.
For example, your application can send custom reminders to both organizers and attendees six hours before the scheduled meeting. You can include links to resources and other instructions within your application.
Configuring Webhooks
For upcoming bookings, select one or more reminders within the booking configuration using the delivery_method: webhook key-value pair.
In the example, the Scheduler API triggers 60 minutes before as a POST request to the "webhook_url" provided.
{
"reminders": [{
"delivery_method": "webhook",
"delivery_recipient": "owner",
"time_before_event": 60,
"webhook_url": "https://example.com/api/booking-webhook"
}]
} POST Body
The page and booking objects in the full request payload provide the context for sending emails or performing other business logic.
{
"booking": {
"recipient_tz": "America/Los_Angeles",
"id": "<BOOKING_ID>",
"location": "Sightglass Coffee, SOMA",
"is_confirmed": true,
"start_time": 1638552630,
"recipient_locale": "en",
"calendar_id": "<CALENDAR_ID>",
"account_id": "<ACCOUNT_ID>",
"recipient_email": "[email protected]",
"title": "Intro Meeting",
"end_time": 1638552600,
"calendar_event_id": "<EVENT_ID>",
"edit_hash": "f5gDjm-DpR2O-YC85Ie9iA",
"recipient_name": "Ada Lovelace",
"additional_field_values": {
"favorite_foods": "Potato chips"
}
},
"page": {
"edit_token": "<EDIT_TOKEN>",
"id": "<PAGE_ID>",
"config": {
"timezone": "America/Denver",
"locale": "en",
"booking": {
"calendar_invite_to_guests": true,
"additional_guests_hidden": false,
"available_days_in_future": 21,
"min_cancellation_notice": 0,
"confirmation_method": "automatic",
"confirmation_emails_to_host": true,
"scheduling_method": "round-robin-maximize-availability",
"min_booking_notice": 0,
"min_buffer": 0,
"opening_hours": [{
"start": "07:00",
"end": "20:30",
"days": [
"M",
"T",
"W",
"R",
"F"
],
"account_id": "<ACCOUNT_ID>"
}],
"confirmation_emails_to_guests": true,
"additional_fields": [{
"allergies": "multi-line text",
"name": "notes",
"label": "Notes",
"order": 1,
"required": false
}],
"name_field_hidden": false
},
"reminders": [{
"time_before_event": 129600,
"delivery_method": "webhook",
"delivery_recipient": "owner",
"webhook_url": "https://example.com/api/booking-webhook"
}],
"appearance": {
"color": "#67f0c9",
"show_week_view": true,
"show_autoschedule": true,
"show_nylas_branding": false,
"company_name": "Foundry 376",
"logo": "https://s3.example.com/nylas-scheduling/43/generic-logo.jpg",
"show_timezone_options": true,
"submit_text": "SUBMIT",
"thank_you_text": "See you soon."
},
"calendar_ids": {
"<ACCOUNT_ID>": {
"booking": "<CALENDAR_ID>",
"availability": [
"<CALENDAR_ID>"
]
}
},
"event": {
"location": "Sightglass Coffee, San Francisco",
"capacity": -1,
"title": "Coffee Meeting",
"duration": 30
}
},
"modified_at": "2020-09-09",
"app_organization_id": 876453,
"slug": "SLUG",
"name": "PAGE_NAME",
"created_at": "2020-09-09",
"app_client_id": "<NYLAS_CLIENT_ID>"
}
} POST Response
Your service must reply according to these two conditions.
200OK status code- 30 or fewer seconds response time
Sending Notifications to Participants
Configuring your application's webhook timings allow for flexible business logic. Webhooks deliver depending on different time intervals and update through booking configurations in code.
Send notifications based on event time by using the booking information for opening_hours.start and applying relevant conditions in the webhook.
For webhooks set to time intervals greater than the difference in time between an event and its booking, all applicable webhooks go through immediately.
Immediate Delivery
The time interval conditions within webhooks allow for sending immediate notifications.
Booking on Short Notice Notifications
Webhooks reflect all applicable time interval notification configurations after booking. If the booking time is sooner than the time interval for notification, then the webhook triggers immediately. The time_before_event value refers to the time interval in minutes.
| Time interval | Booking time | Delivery |
|---|---|---|
| 1 hour before | 3 hours before | 1 hour before |
| 1 day before | 3 days before | 1 day before |
| 1 hour before | 30 minutes before | Immediately |
| 1 week before | 1 day before | Immediately |
"reminders": [{
"delivery_method": "webhook",
"delivery_recipient": "both",
"time_before_event": 60,
"webhook_url": "https://test.com/callback"
}], Soonest Possible Example
Webhook conditions set to always evaluate as true trigger as soon as the booking occurs. In this example, the time_before_event trigger in minutes is set to a value greater than the avalaible_days_in_future value in days.
{
"access_tokens": [
"<ACCESS_TOKEN>"
],
"config": {
"booking": {
"available_days_in_future": 14,
"scheduling_method": "round-robin-maximize-fairness"
},
"calendar_ids": {
"<ACCOUNT_ID>": {
"availability": [
"<CALENDAR_ID>"
],
"booking": "<CALENDAR_ID>"
}
},
"reminders": [{
"delivery_method": "webhook",
"delivery_recipient": "customer",
"time_before_event": 20160,
"webhook_url": "https://test.com/callback"
}],
"timezone": "America/Los_Angeles"
}
} Job Status
The job status webhook triggers notifications for failed bookings. A job.failed webhook and an email to the host triggers for any events that can't be added to a calendar.
Delivery Attempts
Scheduler API configurations retry webhooks three times over several minutes when service is unavailable or endpoints return any other status code than 200. A webhook delivery failure for one webhook payload doesn't affect other delivery attempts. Other bookings using the same endpoint continue to attempt to deliver.
Booking webhooks don't trigger when either party cancels or for removing the event from the host's calendar. Webhooks also don't arrive if they can't trigger before the start time of the booking.