Nylas Webhook Notifications API

Your application receives information about changes to user accounts and data through Nylas webhooks. 🔍 The term "webhook" can refer to any of three component parts: a location where you receive notifications (the "webhook URL" or "webhook endpoint"), a subscription to events that you want notifications for ("webhook triggers"), or the information payload that is sent when a trigger condition is met (the "webhook notification"). We try to be specific in this documentation to avoid confusion. To configure webhooks, you first need a webhook URL in your project where your app can receive incoming webhook payloads, and a list of triggers that you want to receive notifications for. See the [list of available trigger types](/docs/reference/notifications/) for more information. Webhooks in Nylas are not compatible with Ngrok because of throughput limiting concerns. Nylas recommends you use [VS Code port forwarding](https://code.visualstudio.com/docs/editor/port-forwarding), [Hookdeck](https://hookdeck.com/), or a similar webhook tool. ## Testing webhooks Nylas includes two utility API endpoints to help you identify problems with your webhook configuration. Use the [Send Test Event endpoint](/docs/reference/api/webhook-notifications/send_test_event/) to check if your project's webhook destination is configured correctly. This endpoint sends a test webhook payload, and listens for a success acknowledgement from the webhook destination. Use the [Get Mock Notification Payload endpoint](/docs/reference/api/webhook-notifications/get_mock_webhook_payload/) to see example notification payloads for the different Nylas events. ## Monitor grant status The most important webhooks to subscribe to are those related to grant status: `grant.created`, `grant.updated`, `grant.deleted`, and `grant.expired`. They allow you to automate important grant lifecycle processes, like onboarding messages, data refreshes, and backend deletions. The `grant.expired` trigger notifies you when a user needs to re-authenticate their account. When you receive a `grant.expired` notification, you can take appropriate action (for example, notifying the user or starting a background re-authentication process). 📝 When a grant becomes invalid, Nylas cannot access the user's data and does not send you webhook notifications about it. When you re-authenticate a grant, Nylas looks at when the grant last authenticated successfully. If it was less than 72 hours ago, Nylas looks for any changes that happened since the time of the last successful sync, and sends you notifications about them. This can be a lot of notifications. If the grant has been out of service for more than 72 hours, Nylas does _not_ send backfill notifications. In this case, look for the `grant.expired` and `grant.updated` notifications, and query the Nylas API for objects that changed between those timestamps. ## iCloud limitation for Calendar notifications Because iCloud doesn't support the `primary` property for calendars, Nylas sends `calendar.updated` notifications for changes to all calendars on an iCloud account. ## Gmail metadata notifications Nylas sends [`message.created.metadata` and `message.updated.metadata` notifications](/docs/reference/notifications/#message-metadata-notifications) for Google grants that include the `/gmail.metadata` scope. These notifications have limited data because of the restrictive scope. Even if a grant has more permissive scopes, Google falls back to the `/gmail.metadata` permissions. When you subscribe to a `message.*` webhook trigger, Nylas automatically sends `message.*.metadata` notifications as well. You don't need to subscribe to these triggers separately, and they don't appear as a configuration option in the Nylas Dashboard. For more information, see our list of [available trigger types](/docs/reference/notifications/). ## Payload size limit and truncation Nylas sends webhook notifications as JSON payloads that contain the object that triggered the notification, up to a maximum payload size of 1MB. If a webhook notification exceeds the size limit, Nylas truncates the payload by removing the body content, and adds the `.truncated` suffix to the webhook trigger name (for example, `message.created.truncated`). This reduces the size of the payload and improves performance. When you receive a truncated webhook notification, you'll need to re-query the Nylas APIs to get the data. For example, if you receive a `message.updated.truncated` notification, make a [Get Message request](/docs/reference/api/messages/get-messages-id/) that includes the message ID. If you subscribe to a webhook trigger that can be truncated, Nylas automatically sends you `.truncated` notifications as well. You don't need to subscribe to webhook triggers with the `.truncated` suffix separately, and the suffix doesn't appear as a option in the Nylas Dashboard. See the [list of available trigger types](/docs/reference/notifications/) for more information. You can monitor for `.truncated` notifications to create automations that retrieve the full affected object. For example, you can create an automation that makes a [`GET /v3/grants//messages/` request](/docs/reference/api/messages/get-messages-id/) when your application receives a `message.updated.truncated` notification. ## Payload compression Set `compressed_delivery` to `true` on a webhook destination and Nylas gzip-compresses each notification before `POST`ing it to your endpoint, adding a `Content-Encoding: gzip` header. Compressed payloads are also opaque to firewalls and WAFs that would otherwise block requests containing HTML in email bodies. Verify the `X-Nylas-Signature` header against the raw compressed body _before_ decompressing. For full setup and when to use it, see [Reducing payload size with compression](/docs/dev-guide/best-practices/compression/). ## How to handle webhook failures Nylas implements "circuit breaker" logic to handle failing webhooks. See [improvements to failure notifications](/docs/new/in-v3/webhooks-changes/#improvements-to-webhook-failure-notifications) and [Failing and failed webhooks](/docs/v3/notifications/#failing-and-failed-webhooks) for more information. - **Failing state**: If Nylas cannot deliver a webhook notification to the destination endpoint for 95% of webhooks over a 15-minute period, Nylas marks the endpoint as `failing` but continues sending notifications to it. Nylas also sends you a message when this happens so you can troubleshoot the issue. - **Failed state**: If Nylas cannot deliver 95% of webhook notifications to a `failing` endpoint over the next 72 hours, Nylas marks the endpoint as `failed` and stops sending notifications to it. Nylas also sends you a message when this happens so you can address the issue. ⚠️ Nylas does not automatically restart or reactivate failed webhooks. This change gives you full control over when your webhook endpoint becomes active again, so you can verify that it's working as expected before you restart normal webhook traffic. ## Duplicate webhook notifications Nylas guarantees "at least once" delivery of webhooks. You might receive duplicate webhook notifications because of the provider's behavior (for example, when Google and Microsoft Graph send upserts). ## Webhook triggers - `contact.updated`: A contact was modified or updated. - `contact.deleted`: A contact was deleted. - `calendar.created`: A calendar was created. - `calendar.updated`: A calendar was updated or modified. - `calendar.deleted`: A calendar was deleted. - `event.created`: An event was created on a user's calendar. - `event.updated`: An event was updated or modified. - `event.deleted`: An event was deleted. - `grant.created`: A new grant was authenticated. - `grant.updated`: A grant was modified, updated, or re-authenticated. - `grant.deleted`: A grant was deleted as a result of the user making a [Delete Grant request](/docs/reference/api/manage-grants/delete_grant_by_id/). - `grant.expired`: A grant's credentials have expired, and the user must re-authenticate. - `message.created`: A message was created. - `message.created.cleaned`: A cleaned (parsed) version of a newly created message was processed. Requires Clean Conversations to be enabled. - `message.updated`: A message was updated. - `message.send_success`: A scheduled message was sent and delivered successfully. You must set the `send_at` parameter in a message to use this trigger. For more information, see [Schedule messages to send in the future](/docs/v3/email/scheduled-send/). - `message.send_failed`: A scheduled message was sent, but was not delivered. You must set the `send_at` parameter in a message to use this trigger. For more information, see [Schedule messages to send in the future](/docs/v3/email/scheduled-send/). - `message.bounce_detected`: (Available for Google, Microsoft Graph, iCloud, and Yahoo) A message bounced or was not delivered. - `message.opened`, `message.opened.legacy`: A participant opened a tracked message. - `message.link_clicked`, `message.link_clicked.legacy`: A participant clicked a link in a tracked message. - `thread.replied`, `thread.replied.legacy`: A participant replied to a message in a tracked thread. - `folder.created`: A folder or label was created. - `folder.updated`: A folder or label was modified or updated. - `folder.deleted`: A folder or label was deleted. - `booking.created`: A new Scheduler event was created. - `booking.rescheduled`: A Scheduler event was rescheduled through Scheduler. - `booking.cancelled`: A Scheduler event was cancelled through the Scheduler. - `booking.pending`: A pending booking was created. - `booking.reminder`: Nylas sent a reminder about a booking. For more information on webhook trigger types, and for schema examples, see the [notification schemas](/docs/reference/notifications/). ## Scheduler events in Calendar webhooks Calendar events that Nylas Scheduler creates also produce standard `event.*` notifications. Nylas stamps these events with metadata so you can identify them in Calendar webhooks: - `source`: Always `scheduler`. - `key5`: The Scheduler Configuration ID. - `scheduler_last_start`, `scheduler_last_end`, `scheduler_updated_at`: Unix timestamps (as strings) that record the meeting time Scheduler most recently set, at booking creation and on each reschedule. To tell Scheduler-driven changes apart from edits made directly on the organizer's calendar, compare an `event.updated` notification's `when` times against `scheduler_last_start` and `scheduler_last_end`: if the times match, the change came through Scheduler (Nylas also sends a `booking.rescheduled` notification), and if they differ, the event was changed directly on the calendar. These metadata entries share the event's customer-visible `metadata` object. If you update an event's metadata using the Events API, include the Scheduler-stamped entries in your request — updates replace the metadata object as a whole.