public-beta-v3

Webhooks in API v3

The Nylas API v3 is in public beta. It might contain bugs, and might change before it is generally available. See the v3 Beta documentation for more information.

The Nylas v3 APIs include improvements to webhooks that simplify how you listen for user activity. These include both performance improvements and architecture changes to simplify and streamline your implementation, and reduce round-trip queries to the providers.

Previously, Nylas webhooks only reported changes on the provider and included only a relevant object ID, without including any details about the objects that changed. It was up to your app to make an additional query to access those details. In v3, Nylas webhooks include the object that changed so you can eliminate additional queries.

Configuring v3 webhooks

Nylas API v3 uses two new server endpoints, and includes the API version (/v3/) in the endpoint URI, however the process of creating and updating them is largely the same. See the Changes and improvements in v3 page for more details.

To create a webhook, you must include two things in your API request: A callback_url and a list of the trigger_types you want to listen for. Nylas sends webhook notifications for the triggers you include in this parameter.

curl --location 'https://api.us.nylas.com/v3/webhooks/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <gotten in Obtain API Key step>' \
--data-raw '{
"trigger_types": [
"grant.created",
"grant.deleted",
"grant.expired",
],
"description": "local",
"callback_url": "<your webhook url>",
"notification_email_addresses": [[email protected], [email protected]]
}'

Both v2 and v3 Webhooks use the same algorithm to verify the "Challenge" parameter.
When you create or activate a webhook, Nylas makes a GET request to the endpoint with a challenge query parameter. Your application must return the exact value of the challenge in the response body within 10 seconds. See the Challenge parameter in V2 page for more details.

Trigger types available in v3 Beta

Not all webhooks are available in v3 Beta. Equivalent webhooks for all v2 triggers will be available when v3 reaches General Availability (GA) release.

The available trigger types in v3 include:

calendar.created: A new calendar was created.
calendar.updated: A calendar was updated or modified.
calendar.deleted: A calendar was deleted.
event.created: A new event on a calendar was created.
event.updated: An existing event on a calendar was updated or modified.
event.deleted: An existing event on a calendar was deleted.
grant.created: A grant was created. This is the v3 equivalent of the "Account connected" webhook.
grant.updated: An existing grant was modified or updated. This trigger also includes re-authentication.
grant.deleted: A grant was deleted by the user calling the "Delete grant" API.
grant.expired: A grant expired, and the end user must re-authenticate. Use this to trigger notifications to administrators or users to take action.
message.send_success: A scheduled email message was sent successfully.
message.send_failed: A scheduled email message was sent, but was not delivered.
message.bounce_detected: (Gmail and Graph only) Nylas detected that an email message bounced or was not successfully delivered. Use this trigger to create bounce notifications and take appropriate action.
message.created: An email message was created.
message.updated: An email message was updated.

Trigger types coming soon:

message.deleted: An email message was deleted.
contact.created: A contact was created.
contact.updated: A contact was created.
contact.deleted: A contact was deleted.
folder.created: An email folder was created.
folder.updated: An email folder was updated.
folder.deleted: An email folder was deleted.

Tip: You can use the Get Mock Payload endpoint to retrieve an example webhook payload.

Webhook changes and improvements in v3

Webhook payload format changes

In v3, webhook notifications no longer return as an array of object IDs related to the webhook. Instead, they return a single JSON payload containing 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.

Tip! You can use the new Get mock payload endpoint to see sample payloads for different triggers, so you can familiarize yourself with the updated payload format.

Webhook payload size limits and truncation

Nobody wants to have to deal with dedicated scaling and infrastructure for an occasional huge message. If an object returned with a webhook payload is larger than 1 MB, large fields such as message body and event description are omitted. This helps reduce the payload size and improves webhook performance.

When a webhook payload is truncated, Nylas adds .truncated to the end of the returned webhook trigger name to notify you that the payload is incomplete. You don't need to subscribe to triggers with .truncated suffixes separately, as they are included in the normal trigger subscription, and the suffix does not appear as a subscription option in the v3 Dashboard.

Improvements to webhook signatures

In previous versions, Nylas webhooks used HMAC-SHA256 signatures with the client_secret as the signing key. In API v3, Nylas generates a new webhook secret when each webhook is created to use as the signing key. You can get the webhook secret when you create a webhook destination, and you can use the /v3/webhooks/<id>/rotate-secret endpoint to update the webhook secret.

The encoding algorithm for both Nylas API v2 and v3 is HMAC-SHA256.

Deprecating webhook notifications for historic sync

Webhooks in v3 do not support historic sync. This means that when a customer authenticates for the first time, you will not receive webhook notifications for email or calendar events that occurred before the user first authenticated. In v3, after the user authenticates you can query the Nylas endpoints to retrieve any information you need - instead of relying on webhooks.

Re-authenticating grants and webhook notifications

In API v3, the authentication and re-authentication processes do not produce historical webhooks (webhook notifications for events that happened before the auth completed)

This means that when a grant expires or is otherwise invalidated in v3, re-authenticating does not produce webhook notifications for events that occurred while the grant was out of service.

To find and backfill events that occurred while a grant was invalid, find the timestamps on the grant.expired and grant.updated webhooks that correspond to the grant in question. You might want to log or otherwise save these notifications when you receive them so you can query and analyze them later.

As soon as the user re-authenticates, you can use the Nylas APIs to directly query the provider for changes that happened during that time. You do not need to wait for any synchronization status to complete.

Adding webhook descriptions and notification emails

You can now set a description and notification_email_addresses for each webhook. Use the description to clarify each webhooks' purpose, for example prod or testing environments.

Use the notification_email_addresses option to add a list of addresses that should get a notification if the webhook is failing. These should be either the webhook's "owners" or someone who can troubleshoot and correct your webhook handling infrastructure.

Improvements to webhook failure notifications

In addition to adding owner emails, webhooks in Nylas API v3 include improvements to how failing webhooks are handled. This is sometimes called "circuit breaker" logic.

With API v3, if message delivery fails to your endpoint for 95% of the webhooks in a 15-minute timeframe, Nylas marks your webhook endpoint as "failing" but continues sending webhooks to it. Nylas also sends you a warning message when this happens so you can troubleshoot. This behavior is the same as in API v2.

In both API v2 and v3, if delivery to your endpoint continues to fail for 95% of messages over the next 72 hours after it's marked as "failing", Nylas marks the specific callback URL as "failed" and stops sending notifications to it. Nylas also sends an email alert when a webhook endpoint is marked as "failed" so you can address the issue.

However, in v3 the Nylas does not automatically change a failed webhook status back to "active" as it did in v2. 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 back to "active".

In v3, Nylas does not automatically restart or reactivate webhooks that were in a "failed" state.

This change makes sure you have full control over when your endpoint becomes active again, so you can thoroughly verify that it's working as expected before restarting normal webhook traffic.

New webhook triggers for email send status monitoring

You can use the message.send_success, message.send_failed and message.bounce_detected webhooks to monitor the status of the email you send using the Nylas API. For these to work, you must set the send_at attribute, and send the message using the Nylas v3 API.

New webhook endpoints for testing and maintenance

Nylas API v3 introduces new endpoints to make testing and maintaining webhooks easier.

Get mock payload: This endpoint allows you to retrieve a mock payload for testing purposes.
Send test event: Use this endpoint to send a test event to a specific callback_url so you can verify the functionality and responsiveness of the webhook.
Get IP addresses: This endpoint provides a list of IP addresses associated with the specified webhook for allowlisting or other security purposes.
Rotate webhook secret: This endpoint allows you to update the secret key used to encode the X-Nylas-Signature header on webhook requests, for enhanced security and authentication.

Suggested changes for v3 webhook infrastructure

Make sure your webhook receiver can handle up to 1MB webhook notification payloads. Changes to the v3 webhooks shouldn't change the number of webhooks you receive much (unless your v2 implementation uses historical webhooks, see below), but it will change the amount of data processed for each one. Make sure that any systems that autoscale are prepared to accept and process larger webhook payloads. You might want to run some tests using v3 webhooks to see what your average payload size is.
You can remove (or adapt, see below) the logic you used to re-query the Nylas API for an object by ID, and instead parse the webhook payload.
You can adapt your re-query logic to listen for .truncated webhooks (for objects over 1MB in size), and then query for the rest of the object information as needed.
No more historical sync means that if you previously used webhooks to access users' historical data, you'll need to query for that data the first time a user authenticates instead. You can use the grant.created webhook to listen for this so you can trigger this logic.