Version:
Only show these results:

Upgrade webhooks from v2.x to v3

API v3 introduces many improvements and changes to webhook functionality which are explained below. This page is to help guide you through the process of upgrading a v2 Nylas implementation so you can use v3.

✨ Want a version of this guide tailored to your project? Check out Nylas Migration Station!

The process of upgrading your webhook implementation can be divided into the following steps:

  1. Set up a test environment
  2. Set up webhooks for testing
  3. Make changes and observe data
  4. Upgrade v2 webhook code
  5. Build v3 webhook infrastructure for scale

You may need to return to this page as you upgrade the individual Nylas product APIs, so you can test with different types of object data.

Before you start, you should read up on the changes to webhooks in v3 so you understand the why as well as the what. The changes are described in detail below.

Nylas v3 architecture changes that affect webhooks

Nylas API v3 is a quick provider-side query system which no longer uses long-running data sync jobs. This means that the job.successful, job.failed, account.running, account.stopped, and account.sync_error webhook triggers are no longer needed.

In addition, the concept of "grants" in v3 replace "connected accounts" from v2. This means that instead of monitoring for account.invalid notifications, you should subscribe to the grant.expired trigger instead.

This also means that the Delta endpoint is deprecated in API v3. You should now track changes using the message.updated, event.updated, and other "updated" webhook notifications. For more information, see the notification schemas.

No webhook notifications for historic sync

Nylas no longer syncs historical data (from before the user first authenticated), and no longer sends webhook notifications for this historical data. This means that when an end user authenticates for the first time, you do not get webhook notifications for Email or Calendar events that occurred before the user authenticated.

After the user authenticates, you can query the Nylas API endpoints to get any historical data you might need, instead of relying on webhook notifications for historical data.

Webhook notification backfill for expired 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.

Webhook notifications now include object data

This is the big one: in Nylas API v3, webhook notifications no longer return an array of object IDs related to the webhook trigger. Instead, they return a single JSON payload that contains the object that triggered the notification. If your webhook listener is expecting an array, you must update it to accept and parse the JSON payload instead.

💡 You can make a Get Mock Payload request to see sample webhook notification payloads. Use this to get familiar with the new webhook notification formats.

Changes to Email API webhooks

The following sections describe changes to Email API webhooks in more detail.

New triggers for email send and bounce status

You can use the new message.bounce_detected trigger to get a notification if an email you sent using the Nylas API has bounced. This trigger is only available for Google, Microsoft, iCloud, and Yahoo accounts.

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.

Pub/Sub requirement for Google message webhooks

If your project monitors for message-related webhook notifications from Google providers, you must set up a Google Pub/Sub queue to make sure you get your webhook notifications in real-time.

Message webhook size limits 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 (usually the message body). 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 webhook 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.

Changed webhook mechanics

API v3 introduces some changes in webhook security, and webhook retries.

You can now rotate webhook signatures

In previous versions of the API, Nylas webhook destinations used HMAC-SHA256 signatures with your application's client_secret as the signing key.

In API v3, Nylas generates a new webhook secret for each webhook destination when it is created, and returns the value as webhook_secret in the success response. These webhook secrets are used as unique signing keys, and the signatures are still HMAC-SHA256-encoded.

The webhook secret is used to sign future requests to update the webhook. If you want to update a webhook secret, you can now make a POST request to the Rotate Secret endpoint.

See Respond to webhook verification request for more details.

Failed webhooks are no longer restarted

API v3 improves how Nylas handles webhook destinations that are failing or failed.

If Nylas cannot deliver 95% of notifications to a subscribed destination over a 15-minute period, Nylas marks the destination as failing but continues to send notifications 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 API v2.

In both API v2 and API v3, if delivery to the destination keeps failing 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 another email message when this happens so you can address the issue.

Nylas v3 also adds the webhook_delivery_attempt counter to the webhook notification payloads, so you can see how many times Nylas tried to deliver the notification.

⚠️ Nylas API v3 does not automatically restart or reactivate webhook destinations that were in a "failed" state. When you get a webhook failure notification, you should check your webhook listener, resolve any issues, and — only when you're confident that the issues have been resolved — change the webhook's status to active.

Adding this "circuit breaker" logic makes sure Nylas doesn't start sending messages to a troubled webhook destination until you explicitly tell it to. This allows you to confirm that the destination is working as expected before restarting normal webhook traffic that could otherwise cause it to fail again.

Improved webhook destinations

API v3 brings improvements and changes to how you set up webhook destinations. You can create webhook destinations either from the v3 Dashboard, or by making a POST /v3/webhooks request.

Webhook descriptions and notification email addresses

In Nylas API v3, you can set a description and notification_email_addresses when you create each webhook subscription.

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.

Callback URL is now called Webhook URL

The callback_url used by webhook subscriptions is now called webhook_url to make it explicit what this address is used for. This also helps distinguish it from the callback_uri and redirect_uri used by OAuth.

New webhook utilities

Nylas API v3 introduces new Webhook endpoints to make testing and maintenance easier. Use these endpoints to quickly get a "test" payload, to see the IP addresses for your webhooks, and to rotate webhook credentials.

  • 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_url so 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-Signature header on webhook requests, for enhanced security and authentication.

Got all that? Let's begin.

Set up a test environment

Nylas strongly recommends that you do not test your v3 upgrades in a production environment first. Before you begin testing, make sure you set up and are using a test or development Nylas application, or are using the v3 Sandbox application. This prevents upgrade testing activities from impacting production users.

From your Nylas application, generate an API key. API keys are a new concept in API v3, and are specific to each application. You'll use the API key as Bearer authorization header in requests to the webhook API endpoints. This replaces the client_secret used to authorize requests in v2.x.

Use v3 authentication to create a grant

Before you start working on webhook subscriptions and delivery, you must first use v3 authentication of some type to use v3 methods. This could mean either that you test with a very limited number of accounts using the Nylas v3 Sandbox and the authentication connectors it provides, or that you upgrade an authentication system on a dev or test environment. You can't receive webhook notifications about user accounts or their data until you do this.

Follow the steps in the Upgrading Authentication guide and contact Nylas Support if you run in to any issues.

You might need to check that you have the correct API v3 Webhook Scopes in your authentication systems. If you decide to use the Sandbox, you can only use the scopes listed for each connector, and this might limit your testing.

When you have authentication set up, connect an account to your application so that Nylas creates a grant. Without a grant, you have no connected account to listen to for changes, so this step is required.

Set up webhooks for testing

Next, you'll set up a system to listen for webhook messages, register it with your Nylas test application, and subscribe it to triggers.

Set up a webhook URL

The next task is to set up a program that can "listen" at a specific URL. This will be the URL you set as the webhook_url when you add webhook destination. This listener must be able to respond to the Nylas query to confirm the endpoint. See Respond to webhook verification request for more details.

If you don't want to run a full development stack of your project just yet, for testing purposes the easiest way to set up a listener is using VS Code port forwarding, or using a service like Hookdeck or a similar webhook tool. Local webhook testing is coming soon for the Nylas v3-compatible SDKs

⚠️ Not compatible with Ngrok. Webhooks in Nylas API v3 are not compatible with Ngrok because of throughput limiting concerns.

Create a webhook destination

Next, create the webhook destination for your testing application, either using the v3 Dashboard, or by making a POST /v3/webhooks request. You should give them a description so you know that they're for testing, and include the URL of your webhook listener.

As part of this process you specify the webhook triggers you want to subscribe to. You might want to start with just one or two trigger types for early testing. Make sure your authentication systems include the correct scopes for the triggers you want to test.

Make changes and observe data

Next, send some email messages, or update events or other information using the account you connected when you created the grant. If you get errors, check the Webhook API documentation for error code information, or contact Nylas Support.

When you have your first webhooks working, you can either start upgrading other Nylas APIs and come back to this page later, or continue on to upgrade your v2 project's use of webhooks.

Upgrade v2 webhook code

How you perform this step is up to you and your individual development processes. We're including the following list of API endpoints that changed, and webhook triggers that changed, for reference. (Most of the webhook triggers have not changed!)

If you have questions, comments, or suggestions on how we could improve this page, drop us a line!

Once you're done upgrading your webhooks, you should think about scale.

Migrated webhooks API endpoints

Removed webhooks API endpoints

  • Get Nylas webhook IP addresses: /a/<client_id>/ip_addresses (In v2, this endpoint was listed under the Application endpoints as "Return Application IP Addresses".)

Migrated webhook triggers

  • account.connected → grant.created

Removed webhook triggers

  • account.running: No longer needed due to architecture changes.
  • account.stopped: No longer needed due to architecture changes.
  • account.invalid: Use grant.deleted or grant.expired instead.
  • account.sync_error: No longer needed due to architecture changes.
  • contact.created: Use contact.updated instead, this triggers on contact creation.
  • job.successful: No longer needed due to architecture changes.
  • job.failed: No longer needed due to architecture changes.

New webhook triggers

  • grant.deleted
  • grant.updated (Includes re-authentication.)
  • grant.expired
  • message.send_success (Scheduled messages only.)
  • message.send_failed (Scheduled messages only.)
  • message.bounce_detected (Available for Google, Microsoft Graph, iCloud, and Yahoo.)
  • message.opened
  • message.link_clicked
  • thread.replied

Unchanged webhook triggers

  • message.created
  • message.updated
  • calendar.created
  • calendar.updated
  • calendar.deleted
  • event.created
  • event.updated
  • event.deleted
  • contact.updated
  • contact.deleted
  • folder.created
  • folder.updated
  • folder.deleted

Build v3 webhook infrastructure for scale

In general, you should prepare for changes in webhook notification size, which might mean you should Build for scalability.

Nylas also suggests you make the following changes to accommodate the v3 webhook infrastructure if you're migrating from API v2.x.

  • Make sure the webhook listener that you subscribe to message triggers can handle webhook notification payloads up to 1MB in size. Changes to the v3 webhooks shouldn't drastically impact the number of notifications you get (unless your API v2 implementation uses historical webhooks), but it will change the amount of data processed for each notification.
    • Make sure that any systems that autoscale are prepared to accept and process larger webhook payloads. For more information, see Build for scalability.
    • You might want to run some tests using v3 webhooks to determine your average payload size.
  • You can remove or adapt the logic you used to re-query the Nylas API for an object using its ID, and instead parse the webhook notification payload.
  • You can adapt your re-query logic to listen for .truncated webhook triggers (for objects over 1MB in size), then query for the rest of the object's information as needed.
  • No more historical sync means that if you previously used webhooks to access your end users' historical data, you must query for that data the first time an end user authenticates instead. You can use the grant.created webhook to listen for new grants so you can trigger the query logic.