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