Nylas Docs

The Nylas Developer Hub

Welcome to the Nylas developer hub. You'll find comprehensive guides and documentation to help you start working with Nylas as quickly as possible, as well as support if you get stuck. Let's jump right in!

Developer Guide

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 delivery_method: webhook:

{
  ...
  "reminders": [
    {
      "delivery_method": "webhook",
      "time_before_event": 60, // minutes
      "webhook_url": "https://example.com/api/booking-webhook"
    }
  ]
    ...
}

The scheduling API will trigger a POST request to the URL you provide, with the booking and page objects in the request payload giving you all the context you need to send emails or perform other business logic:

POST Body:

 {
      "page": {
        "name": "1:1 Coffee Meeting",
        "slug": "test-page"
        "config": {
          ...
        },
      },
      "booking": {
        "id": 50,
        "title": "Intro Meeting",
        "edit_hash": "f5gDjm-DpR2O-YC85Ie9iA",
        "is_confirmed": true,
        "location": "Sightglass Coffee, SOMA",
        "recipient_email": "[email protected]",
        "recipient_name": "Nylas Swag",
         "recipient_locale": "en",
        "start_time": 1563473700,
        "end_time": 1563476400,
        "additional_field_values": {
          "favorite_foods": "Broccoli"
        }
      }
    }

POST Response

  • Your service must reply with a 200 OK status code.
  • Your service must reply within 30 seconds.

Error Handling

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.

Webhook Timing

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 time_before_event to 20160.) This will ensure that as soon as a meeting is booked, the reminder is overdue and will be sent immediately.

Job Status

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.

Updated 5 months ago

Scheduler Hooks and Job Status


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.