Why do I need to handle both message.created and message.updated webhooks in Nylas v3?

Answer:

With Nylas v3, there's been a fundamental change in how webhook notifications are handled compared to v2. This article explains the changes and best practices for handling webhooks.

Architectural Changes
In v3, Nylas has moved to a direct provider notification model, eliminating the message storage layer used in v2. This change brings several benefits:

• Enhanced security and privacy (no message data storage)
• Real-time updates directly from providers
• More accurate representation of provider behavior

Impact on Webhook Behavior (This is caused by provider behavior)
Due to this architectural change, webhook behavior now directly reflects provider actions. For example:

• When a message is sent, providers may immediately move it from a transient Outbox to the Sent folder
• Google and Graph do not distinguish between create and update events; they send an "upsert," leaving it to us to determine the appropriate webhook type. Occasionally, this can result in the event being mislabeled. We're working on improvements for this, but we can't prevent all mislabeled or duplicated webhooks.
• This folder movement triggers a message.updated webhook
• Nylas applies webhook debouncing to prevent excessive notifications

At the moment, based on our internal findings, this behavior — where a message.created is followed by a message.updated (for example, to reflect a folder change) — is most commonly seen with Graph and IMAP providers. We’ve noticed it’s much less frequent with Google accounts, though it can still occasionally happen there as well.

Best Practices
To ensure reliable message tracking:

1. Handle both message.created and message.updated webhooks

2. Treat these webhooks as upserts

When you receive a `message.updated` or `message.create` webhook, you should fetch the corresponding message ID in the grant. If the message doesn't exist, create it; if it does, update it.

Optimization Tips
To manage increased webhook traffic:

• Use webhook field selection to reduce payload size
• Only fetch full message content when needed
• Process webhooks as upserts to handle both created and updated events efficiently

Resource:
Limitations for sending messages

Updated April 24, 2025 19:03