Webhook best practices
This page includes tips and architecture considerations when implementing Nylas webhook monitoring.
Testing webhooks in a dev application
The best way to test webhooks is on a development application with only a few users. This prevents you from being overwhelmed by the number of triggered webhooks, so you can test and fine-tune your webhook notifications before setting them up on a production-volume app.
Monitor end-user account status
The most important webhooks to subscribe to are those related to user account status:
account.connectedaccount.runningaccount.stoppedaccount.invalidaccount.sync_error
These allow you to trigger important user lifecycle processes like onboarding emails, user data refreshes, and backend deletions.
The account.sync_error webhook specifically allows you to monitor for when an end user needs to re-authenticate, and take appropriate action, whether that's user notification or another backend process to re-authenticate the user.
Enable message tracking
If you are sending email, use message tracking webhooks to simplify how you get notifications when the reader opens the email, clicks a link, or when someone replies to a conversation.
Build for scalability
It’s important to keep scalability in mind when you build your systems to handle webhooks.
For example, an application with 20 connected users all on the same domain, such as a group of work colleagues, with 50 shared calendars can easily generate >20k event.updated webhooks in just a few seconds.
If your webhook endpoint takes more than 10 seconds to handle incoming requests it hits the timeout threshold and the request fails.
If the first send attempt fails Nylas retries using an exponential backoff over the next 20 minutes. However, after five failed attempts, the webhook delivery attempt is marked as failed. If delivery attempts over the next 72 hours fail, the webhook endpoint is marked as failed Nylas stops trying to deliver to it.
Follow the best practices below to ensure you can ingest and these while replying with a 200 response within 10 seconds.
Use asynchronous processing
Nylas strongly recommends that you use asynchronous processing on your webhook endpoint, and use a queueing system so notifications can be processed by a separate service. This separate service should fetch the data about the objects referred to in the webhook notifications, so the webhook endpoint to remains responsive even when bursts of high volumes of webhook notifications occur, for example when new accounts are connected.
Distribute webhook processing
You should expect a large volume of webhook notifications. One way to build for this is to put webhook processing servers behind a load balancer configured for round-robin distribution. This allows you to scale by adding more servers behind the load balancer, so you can provide high availability on your webhook receiving system.
Downtime and error handling
You should monitor your webhook endpoint to make sure it remains available, and to respond if it becomes unavailable. If your webhook endpoint goes down, you should build your app so it restarts the endpoint. Then you can manually fetch the objects that were modified during the downtime, so you can process them appropriately.
Webhook ordering
The Webhook specification does not make any guarantees about delivery or delivery order. This allows webhooks to function regardless of internal architecture, external provider behavior, and transient endpoint errors. Most of the time, the webhook events match the order of events on the related objects, and an object is created before it gets updated.
However, your application should be able to handle rare cases when it receives an updated or deleted trigger before it receives a created trigger for an object. Since the webhook notifications don’t send the actual objects, you can handle this logic when fetching the latest data from the Nylas API.
Webhooks and historical data
When Nylas first connects and starts syncing an account, it syncs both new data and historical data in parallel. This means you might receive a mix of webhooks for historical data and new data until the account is fully synced. You might want to implement logic in your Nylas integration to filter these notifications or prevent them from being sent
To identify webhook notifications for new mail and historical mail, use the linked_at field included in the accounts endpoint and compare it to the date field on the message objects. If the date is earlier than the linked_at time, then the message is historical, and you can choose how to handle it.
Message and draft updates with Deltas
Nylas does not currently offer a webhook trigger to send events when a message is updated, or when a draft is created or updated. You can use delta tracking instead to track this type of change.
Deltas allow you to track changes to accounts in real time. In most cases you should use webhooks instead of deltas, because webhooks are easier to scale and don't require a persistent HTTP connection to Nylas.
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 do, and you send the data on immediately for processing. This also means that a newly-connected or busy account might return a lot of data in the deltas 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: Receives multiple changes in the same request, only finishing the request when it reaches the idle timeout or the connection is closed.
- Long polling: Receives the latest changes in a single request, holds the request open for a batch of changes, waits until the batch is delivered, then closes 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 API reference documentation for an introduction and guide on using this method.