Set up v2 webhooks

This page describes how to set up webhooks for your Nylas v2 applications.

Before you begin

Before you can start using webhooks, your environment must have the following prerequisites:

A Nylas application that can respond to a verification request with a 200 OK.
Webhooks enabled using either the Nylas Dashboard or the Webhooks API.
Data and webhook sync policies configured.
The correct authentication scopes for your webhooks.

Required scopes for v2 webhooks

Webhooks require that you request scopes from the user that allow Nylas to read your end users' data, so it can trigger webhook notifications. Add the minimum required scopes for the webhook triggers you plan to use to your provider auth app.

The table below shows the webhook notification triggers available in Nylas v2 and their minimum required scopes.

Webhook triggers	Scopes
`message.created` `message.link_clicked` `message.opened` `message.updated` `thread.replied`	`email.modify` `email.read_only` `email.send` `email.folders_and_labels` `email.metadata` `email.drafts`
`contact.created` `contact.updated` `contact.deleted`	`contacts` `contacts.read_only`
`calendar.created` `calendar.updated` `calendar.deleted` `event.created` `event.updated` `event.deleted`	`calendar` `calendar.read_only`

Create a webhook

There are two ways to create webhooks for your Nylas applications: using either the Nylas Dashboard or the Webhooks API.

You can create multiple webhooks for each of your Nylas applications, but each webhook must have its own unique endpoint.

Create a webhook in Dashboard

To create a webhook using the v2 Nylas Dashboard, navigate to the Notifications section of your application and select the webhook that you want to add. You must provide the following information:

The full callback_url for the webhook. The URL must direct to an HTTPS endpoint that is accessible from the public internet.
The webhook's notification triggers. For response examples, see the webhook schemas documentation.

Create a webhook using v2 Webhooks API

To create a webhook using the Webhooks API, make a POST /a/{client_id}/webhooks request with the following information:

The full callback_url for the webhook. The URL must direct to an HTTPS endpoint that is accessible from the public internet.
The webhook's notification triggers. For response examples, see the webhook schemas documentation.
The Basic auth credentials, where the username is your application's client_secret.

The code below is an example of a POST request to create a webhook.

POST /a/<client_id>/webhooks HTTP/1.1
Host: api.nylas.com
Authorization: Basic <client_secret>
Content-Type: application/json

{
  "callback_url": "https://example.com/webhook",
  "triggers": [
    "message.opened",
    "contact.updated"
  ],
  "state": "active"
}

Authenticate a webhook

To authenticate a webhook in Nylas v2, use Basic auth with your Nylas application's client_secret. The sample code below shows how to authenticate a webhook using the Nylas Python SDK.

is_genuine = verify_signature(
    message=request.data,
    key=app.config["NYLAS_CLIENT_SECRET"].encode("utf8"),
    signature=request.headers.get("X-Nylas-Signature"),
)

if not is_genuine:
  return "Signature verification failed!", 401

Respond to webhooks

The first time you create a webhook or set an existing webhook's state to active, Nylas checks that it's valid by sending a GET request to its endpoint. The request includes a challenge query parameter for the verification process. Your Nylas application must return the exact value of the challenge parameter in the body of its response.

📝 If you're using a low- or no-code endpoint, you might not receive the Challenge query parameter. If this happens, contact Nylas Support for help with setting up your webhook.

After the webhook is verified, Nylas sends updates to your application using webhook notifications. Your application must respond to those updates with a 200 status code. If Nylas doesn't receive a response, it will attempt to deliver the notification five times before changing the webhook's status to failing.

Every webhook that Nylas sends includes a signature header. You can use this to verify that the data is coming from Nylas.

The Challenge query parameter

When your Nylas application receives a request that includes the challenge query parameter, it's subject to the following requirements:

Your application has up to 10 seconds to respond to the verification request.
- Nylas will not attempt to verify the webhook again if it fails the first check.
- If your application does not respond to the verification request, Nylas returns a 400 BAD REQUEST error.
Your application must return the exact value of the challenge parameter in the body of its response. Do not include any other data — not even quotation marks.
Your application must not use chunked encoding for its response to Nylas' verification request.
Your application must allow the USER-AGENT header with the python-requests value. Without this field, your application might discard inbound API requests.

The code snippet below is an example of a verification request sent by Nylas. The sample adds line breaks to separate the header fields.

{'HOST': '9a98-8-44-123-145.ngrok.io',
'USER-AGENT': 'python-requests/2.27.1',
'ACCEPT': '*/*',
'ACCEPT-ENCODING': 'gzip, deflate',
'NEWRELIC': 'eyJkIjp7InByIjowLjA4MTQyOSwiYWMiOiIyNzAwNjM3IiwidHgiOiIyOTBlMDRmMzAyYzYyYzExIiwidHkiOiJBcHAiLCJ0ciI6IjI5MGUwNGYzMDJjNjJjMTE1MWI2ZGFiNjhmNDU2MmFkIiwiYXAiOiI2NzU1NzQ2MjkiLCJ0aSI6MTY0ODA0NTc0MDAxMCwic2EiOmZhbHNlLCJpZCI6IjlmNzBlMWRkMzY4ZjY1M2RifSwidiI6WzAsMV19',
'TRACEPARENT': '00-290e04f302c62c3151b6dab68f4562ad-9f70e1dd368f653c-00',
'TRACESTATE': '2700637@nr=0-0-2740637-675374629-9f70e1dd368f653c-290e04f302c62c11-0-0.081429-1648045740010',
'X-FORWARDED-FOR': '35.163.173.352',
'X-FORWARDED-PROTO': 'https'}

The Nylas webhook signature

Every webhook notification that Nylas sends (except for v2 Scheduler notifications) includes an X-Nylas-Signature header.

Notifications sent by Nylas v2 include the X-Nylas-Signature header which contains a hex-encoded HMAC-SHA256 signature of the request body, and which uses your application's client secret as the signing key. The signature is for the exact content of the request body — make sure that your processing code doesn't modify the body before checking the signature.

Retry attempts

Nylas tries sending failed webhook messages up to five times, backing off exponentially. Nylas guarantees at least four retries within the first 20 minutes of a webhook failing. All five retries occur within one hour of a webhook failing.

If Nylas can't make a successful POST request to a webhook endpoint after five retries, the system skips the affected notification and continues to send others.

Failed webhooks

Nylas marks a webhook as failing when it receives 95% non-200 responses or non-responses from the webhook's endpoint over a period of 15 minutes.

Nylas marks a webhook as failed in the following circumstances:

It receives 95% non-200 responses (or non-responses) from a webhook endpoint over a period of three days.
It doesn't receive a response from a webhook endpoint over a period of three days.

When a webhook's state is changed to either failing or failed, Nylas sends an email notification to you about the change.

📝 In some cases, the email message notifying you that a webhook is failing or failed might end up in your Spam folder. Be sure to add the notification email address to your allowlist to avoid this in the future!

You can reactivate a webhook through the Nylas Dashboard, or by using the Webhooks API. Reactivated webhooks don't send notifications for events that occurred while they were marked as failed.

Activate and deactivate webhooks

By default, Nylas webhooks are set to active, and you can deactivate them using either the API or from the Nylas v2 Dashboard.

When you deactivate a webhook, Nylas stops sending all events associated with that webhook to your endpoint. When you reactivate a webhook, it starts sending data from the time that it was reactivated.

Nylas does not send notifications for events that occurred while a webhook was inactive.

Deactivate webhooks from the Dashboard

To deactivate a webhook in the Nylas Dashboard, follow these steps:

Log in to the Nylas Dashboard.
From the left navigation menu, select Notifications.
Find the webhook whose state you want to change and set it to inactive.

Deactivate webhooks with the v2 API

To deactivate a webhook in Nylas v2, make a PUT /a/-client_id-/webhooks/-id- request to update the state.

Test webhooks

The Nylas SDKs include tools that allow you to test webhooks locally. See the SDK documentation for more information.

You can also launch a server using the Nylas CLI to listen for incoming webhook events. The tunnel command maintains a server for two hours, and you can restart it an unlimited number of times. See Using webhooks for more information.

🔍 The Nylas APIs block requests to Ngrok testing URLs. Nylas recommends using the Nylas CLI instead, to ensure you receive all data during testing and development.

If you need to add an IP address that sends webhooks to your allowlist, you can use the IP Addresses endpoint to get a list of dynamic IP addresses.

Keep in mind

Webhooks are not compatible with Ngrok because of throughput limiting concerns.
- Nylas recommends you use Visual Studio Code port forwarding, the Nylas CLI, Hookdeck, or a similar webhook tool instead.
Email threads might be incomplete if the sync date is not far enough in the past. Be sure to sync to the start of an account's threads.
Historical webhook settings apply only to new applications.
You should configure your webhook settings before you add connected accounts or grants to your Nylas application.
Changes to webhook settings apply only to accounts or grants that connect after you save the changes.