Changes to webhooks in Nylas v3
This page lists and explains the changes to webhooks and the Webhooks API between Nylas v2.7 and v3.
Notification triggers available in v3
The following trigger types are available in Nylas v3:
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 an end user's calendar.event.updated: An event was updated or modified.event.deleted: An event was deleted.grant.created: A new grant was authenticated. This is the v3 equivalent of the v2account.createdwebhook trigger.grant.updated: A grant was modified, updated, or re-authenticated.grant.deleted: A grant was deleted as a result of the end user making a Delete Grant request.grant.expired: A grant's credentials have expired, and the end user must re-authenticate.message.created: An email message was created.message.updated: An email message was updated.message.send_success: A scheduled email message was sent and delivered successfully. You must set thesend_atparameter in an email message to use this trigger.message.send_failed: A scheduled email message was sent, but was not delivered. You must set thesend_atparameter in an email message to use this trigger.message.bounce_detected: (Available for Google, Microsoft Graph, iCloud, and Yahoo.) An email message bounced or was not delivered.message.opened: A participant opened a tracked email message.message.link_clicked: A participant clicked a link in a tracked email message.thread.replied: A participant replied to an email message in a tracked thread.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.
For more information on webhook trigger types, and for schema examples, see the notification schemas.
Changes to webhooks in v3
The following sections describe changes and improvements to webhooks in Nylas v3.
New triggers for email send status monitoring
You can use the new message.bounce_detected trigger to get a notification if an email you sent using the Nylas API has bounced. (Available for Google, Microsoft Graph, iCloud, and Yahoo.)
If you use the send_at attribute to schedule messages to be sent later, you can use the new message.send_success and message.send_failed triggers to keep informed about the message's status.
Updated webhook payload format
In Nylas v3, webhook notifications are no longer returned as an array of object IDs related to the webhook. Instead, they are returned as a single JSON payload that contains the object that triggered the notification. If your webhook receiver is expecting an array, you should update it to accept and parse the JSON payload instead.
💡 You can use a Get Mock Payload request to see sample webhook notification payloads. Use this to familiarize yourself with the updated payload format.
New webhook descriptions and notification email addresses
In Nylas v3, you can set a description and notification_email_addresses for each webhook that you create.
Use the description to clarify each webhook's purpose (for example, which environment it's used for).
Use the notification_email_addresses field to add a list of email addresses that should be notified if the webhook changes to failing status. These should be either the webhook's "owners", or someone who can troubleshoot and correct the webhook handling infrastructure.
Webhook payload size limit and truncation
Nobody wants to have to deal with dedicated scaling and infrastructure to receive the occasional huge message. If an object returned in a message.created or message.updated notification payload is larger than 1MB, Nylas omits large fields (for example, the message body or event description). This helps reduce the payload size and improves webhook performance.
When a webhook notification's payload is truncated, Nylas adds the .truncated suffix to the returned webhook trigger's name (for example, message.created.truncated).
You don't need to subscribe to triggers with the .truncated suffix separately. They're included in the normal trigger subscription, and the suffix doesn't appear as a subscription option in the v3 Nylas Dashboard. This means that if you subscribe to the message.updated webhook trigger, Nylas automatically subscribes you to the message.updated.truncated trigger as well.
💡 If you want to test your webhook trigger subscriptions, you can use the Mock Payload endpoint to request a truncated mock payload, or the Send Test Event endpoint to request a truncated test event.
Improvements to webhook signatures
In previous versions of the API, Nylas webhooks used HMAC-SHA256 signatures with your application's client_secret as the signing key. In v3, Nylas generates a new webhook secret when each webhook is created (for example, through a POST request to the Webhooks API). These webhook secrets are used as unique signing keys, and the signatures are still HMAC-SHA256-encoded.
If you want to update a webhook secret, you can make a POST request to the Rotate Secret endpoint.
Improvements to webhook failure notifications
Nylas v3 includes improvements to how webhooks with the failing status are handled.
If Nylas cannot deliver a webhook notification to the appropriate endpoint for 95% of the webhooks over a 15-minute period, Nylas marks the endpoint as failing but continues sending webhooks to it. Nylas also sends you an email message when this happens so you can troubleshoot the issue. This behavior is the same as in v2.
In both v2 and v3, if delivery to your endpoint continues to fail for 95% of notifications over the next 72 hours, Nylas marks the specific webhook URL as failed and stops sending webhook notifications to it. Nylas also sends an email message this happens so you can address the issue.
⚠️ Nylas v3 does not automatically restart or reactivate webhooks that were in a "failed" state. When you receive a webhook failure notification, you should check your webhook receiver, resolve any issues, and — only when you're confident that the issues have been resolved — change the webhook's status to active.
The introduction of this "circuit breaker" logic ensures you have full control over when your webhook endpoints become active again, so you can thoroughly verify that it's working as expected before restarting normal webhook traffic.
New endpoints for testing and maintenance
Nylas v3 introduces new Webhook endpoints to make testing and maintenance easier:
- Get Mock Payload: This endpoint allows you to retrieve a mock webhook notification payload for testing purposes.
- Send Test Event: This endpoint sends a test event to a specific
webhook_urlso you can verify the webhook's functionality and responsiveness. - Rotate webhook secret: This endpoint allows you to update the webhook secret used to encode the
X-Nylas-Signatureheader on webhook requests, for enhanced security and authentication.
New webhook delivery attempt tracking field
Nylas v3 adds the webhook_delivery_attempt counter to webhook notification payloads, which records how many times Nylas has attempted to deliver the notification. The counter starts at 1, which represents the first, normal delivery attempt, and increments for each retry. This can help you understand how many times Nylas attempted to deliver a webhook notification to your endpoint before it succeeded.
Nylas webhook notifications use a retry system which continues attempting delivery even if there are later changes. This sometimes can result in your application receiving webhooks notifications for a grant even after it has been deleted.
Deprecated webhook notifications for historic sync
Webhooks do not support historic sync in v3. This means that when an end user authenticates for the first time, you do not receive webhook notifications for Email or Calendar events that occurred before they authenticated.
After the user authenticates, you can query the appropriate Nylas API endpoints to retrieve the information you need, instead of relying on webhooks.
Deprecated Delta endpoint
The Delta endpoint is deprecated in v3. Changes to Messages are now tracked using message.updated notifications. For more information, see the message.updated webhook schema.
Webhook notifications for re-authenticated grants
In v3, Nylas does not produce webhook notifications for events that happened before an end user authenticated with your application. When an end user's grant expires, Nylas stops sending webhook notifications for changes because it can no longer access the account's data.
If the grant expires then becomes valid within 72 hours, Nylas produces webhook notifications for the period that the grant was out of service. This means that your application may experience a high volume of incoming webhooks while Nylas syncs the events. The best practices guide includes suggestions for how to prepare to process a large number of incoming webhooks.
If the grant expires and becomes valid after that 72 hour period, Nylas does not send backfill notifications for events that occurred while their grant was out of service. In this case, look for the grant.expired and grant.updated notifications and query the Nylas APIs for objects that changed between those timestamps.