Scheduler Hooks and Job Status
Scheduler webhooks allow you to build custom logic into your application for upcoming bookings. For example, your application could send a custom reminder to both parties a few hours before the scheduled meeting with links to resources in your application. It's important to set up Scheduler webhooks because it uses them to keep track of changes made to events through calendars. Scheduler will update the corresponding bookings.
To configure webhooks to be sent for upcoming bookings, specify one or more reminders in the page configuration with
"time_before_event": 60, // minutes
The scheduling API will trigger a POST request to the URL you provide, with the
page objects in the request payload giving you all the context you need to send emails or perform other business logic:
"name": "1:1 Coffee Meeting",
"title": "Intro Meeting",
"location": "Sightglass Coffee, SOMA",
"recipient_name": "Nylas Swag",
- Your service must reply with a 200 OK status code.
- Your service must reply within 30 seconds.
If your service is unavailable or your endpoint returns a status code other than 200, the scheduling API will retry webhook delivery three times over several minutes before giving up. Failed delivery of one webhook payload does not stop attempts to deliver to the same endpoint for other bookings.
If a booking has been cancelled by either party or the calendar event has been removed from the host's calendar, booking webhooks are not fired. If webhooks cannot be delivered before the start time of the booking (due to request failures, for example), they are not delivered.
If your application has several webhooks configured for different time intervals (1 week before, 1 day before, 1 hour before), and a booking is made 30 minutes in the future, all three webhooks will be delivered immediately. If your application sends emails or performs logic that is only relevant in a given time period before the event, your webhook code should look at the
booking in the payload and verify that the
start_time of the event matches your constraints.
If you're interested in hearing about every upcoming booking as soon as it is scheduled (rather than at a specific time interval before the booking takes place), set the
time_before_event to a value greater than the maximum future time specified by
available_days_in_future. (For example, if the page allows meetings to be booked 14 days into the future, set
20160.) This will ensure that as soon as a meeting is booked, the reminder is overdue and will be sent immediately.
Subscribe to job status webhook to get notifications for failed bookings. If an event can not be added to a calendar, Nylas will send a
job.failed webhook and an email to the host.