Version:
Only show these results:

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": "ada@example.com",
    "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.

  • 200 OK 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://example.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://example.com/callback"
    }],
    "timezone": "America/Los_Angeles"
  }
}

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.