Best practices for webhooks
📝 This page discusses both Nylas v2.x and v3. For more information about the newest version, see the Nylas v3 documentation.
This page includes best practices, tips, and architecture considerations to keep in mind while implementing webhooks with your Nylas application.
Test webhooks in a development application
The best way to test your webhooks is to use a dev Nylas application that has only a few connected accounts or grants. This prevents you from being overwhelmed by webhook notifications, so you can test and fine-tune them before setting them up on a production-volume application. For more information, see Set up webhooks.
Create webhook ordering logic
The Webhook specification makes no guarantees about delivery of webhook notifications, or their delivery order. This allows webhooks to function regardless of internal architecture, external provider behavior, or transient endpoint errors.
Most of the time, webhook events match the order of events on the related objects, and an object is created before it's updated. Your Nylas application should be able to handle the rare cases when it receives an .updated or .deleted webhook trigger before it receives a .created trigger for an object.
💡 Because Nylas v2 doesn't send the objects associated with webhook notifications, you can handle this logic when fetching the latest data from the Nylas API.
Build for scalability
It's important to keep scalability in mind as you build your systems to handle webhooks. For example, an application with 20 connected accounts on the same domain (for example, a group of work colleagues) and 50 shared calendars can easily generate more than 20,000 event.updated notifications in just a few seconds.
⚠️ If your webhook endpoint takes more than 10 seconds to handle incoming requests, it hits Nylas' timeout threshold and the notification request fails. For more information, see Failed webhooks.
Follow the best practices in the sections below to ensure your Nylas application can effectively ingest and process webhook notifications.
Use asynchronous processing
Nylas strongly recommends you use asynchronous processing on your webhook endpoint along with a queueing system. This allows webhook notifications to be processed by a separate service that fetches data about the objects referred to in the webhook notifications. With this infrastructure, your webhook endpoint remains responsive even during high-volume bursts of webhook notifications (for example, when end users first authenticate with your application).
Distribute webhook processing
You should prepare for your application to receive a large volume of webhook notifications at any time. One way to build for this is to put webhook processing servers behind a load balancer that's configured for round-robin distribution. This allows you to scale by adding more servers behind the load balancer during periods of heavy traffic, so you can maintain high availability on your webhook receiving system.
Monitor webhook endpoints for downtime
You should monitor your webhook endpoints to ensure they remain available, and to respond if they become unavailable.
You should build your application so that if a webhook endpoint goes down, your application automatically restarts it. After the endpoint is available again, you can manually fetch the objects that were modified during the downtime and process them appropriately.
Monitor grant status in v3
Nylas recommends you subscribe to the following webhook triggers to monitor the status of your end users' grants:
grant.createdgrant.updatedgrant.expired
The grant.expired webhook trigger allows your project to monitor for when an end user's grant becomes invalid. Nylas recommends that you set up your project so that when you receive this notification, your project identifies the user, then prompts them to re-authenticate either in-app or by email.
📝 Nylas cannot access an end user's data when their grant becomes invalid, and does not send you webhook notifications about it. When you re-authenticate a grant, Nylas recommends you find the most recent grant.expired and grant.updated webhooks associated with the grant and query for any data that the end user might have received between those times. This lets you backfill any changes that might have happened while the grant was invalid.
For more information about webhook triggers for grants, see the list of notification schemas.
Monitor connected account status in v2
Nylas recommends you subscribe to the following webhook triggers to monitor the status of your end users' connected accounts:
account.connectedaccount.runningaccount.stoppedaccount.invalidaccount.sync_error
The account.sync_error webhook trigger allows you to monitor for when an end user needs to re-authenticate their account. You can use this to set up a re-authentication flow for your users that starts automatically upon receiving an account.sync_error notification.
For more information about webhook triggers for connected accounts, see the list of notification schemas.
Identify webhooks for historic data sync in v2
📝 Webhook notifications for historic data sync are deprecated in Nylas v3. For more information, see Changes to webhooks in Nylas v3.
When a user first authenticates with your Nylas application, Nylas syncs both new and historic data in parallel. For a v2 Nylas application, this means you might receive a mix of webhook notifications for historical data and new data until the connected account is fully synced. Nylas suggests implementing logic to filter historic webhook notifications or prevent them from being sent.
To identify historic webhook notifications for email messages, use the linked_at field included in the v2 Accounts endpoint and compare it to the date field on the Message objects. If the date is earlier than the linked_at time, the message is historical.
Message and Draft updates with Deltas
📝 The Delta endpoint is deprecated in Nylas v3. For more information, see Changes to webhooks in Nylas v3.
You can use Delta tracking in Nylas v2 to monitor changes to Messages and Drafts.
🔍 Deltas are available for Nylas v2 only.
Deltas allow you to track changes to connected accounts in real time. In most cases, Nylas recommends you use webhooks instead of deltas, because webhooks are easier to scale and don't require a persistent HTTP connection to the Nylas platform.
Deltas from Nylas include the entire object that changed in the response. This means you don't need to make an additional data request like you would with webhooks, and you can send the data for processing immediately. This also means that a newly connected or busy account might return a lot of data in delta requests.
Nylas provides the following connection options for delta endpoints:
- Regular HTTP requests: These return immediately, which usually isn't the most efficient way to receive deltas.
- Streaming: These receive multiple changes in the same request, only finishing the request when it reaches the idle timeout or the connection is closed.
- Long polling: These receive the latest changes in a single request, hold the request open for a batch of changes, wait until the batch is delivered, then close the connection. If you use long-polling, you must start a new long poll request every time there are changes, instead of when the timeout is reached.
See the Deltas reference documentation for an introduction and guide on using this method.
Monitor tracked email messages
If your end users are sending email using your Nylas application, you can use Nylas' message tracking webhooks to simplify how you get notifications for certain actions. For more information, see the message tracking documentation.