Webhook Notifications

Your application receives information about changes to user accounts and data through Nylas webhooks.

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 for more information.

Webhooks in Nylas are not compatible with Ngrok because of throughput limiting concerns. Nylas recommends you use VS Code port forwarding, Hookdeck, 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 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 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).

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 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.

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 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 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/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID> request 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 POSTing 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.

How to handle webhook failures

Nylas implements "circuit breaker" logic to handle failing webhooks. See improvements to failure notifications and 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.

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.
• 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.
• 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.
• 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.
• message.intelligence.order: A user received a message containing e-commerce order information. ExtractAI must be enabled.
• message.intelligence.tracking: A user received a message containing shipping information for an e-commerce order. ExtractAI must be enabled.
• 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.