Only show these results:

Using webhooks with Nylas

Webhooks allow your Nylas application to receive notifications in real time when certain events occur. They use a push notification protocol to notify you of events, rather than you having to periodically request ("poll for") the latest changes from Nylas.

Because they're lightweight, webhooks are the best way to get notifications about changes to your application's grants. They can be integrated into your application easily, and scale seamlessly as you grow.

How webhooks work

🔍 The term "webhook" can refer to any of three component parts: a location where you receive notifications (the "callback URL" or "webhook endpoint"), a subscription to events that you want notifications for ("webhook triggers"), or the information payload that is sent when a trigger condition is met (the "webhook notification"). We try to be specific in this documentation to avoid confusion.

When you configure a webhook, you specify a URL that Nylas sends HTTP POST requests to, and subscribe it to specific event types ("webhook triggers"). When a webhook is triggered, Nylas sends information about the affected object to your application. For example, when an end user receives an email message, Nylas can make a POST request to your webhook endpoint to let you know about it. Your application can then use that data to query the Nylas API for details about the object.

A flow diagram showing how Nylas generates and sends webhooks to your application.

You can specify the events that you want to be notified about from the Nylas Dashboard, or using the Webhooks API.

Learn more about how to respond to webhooks, and see the Webhooks reference documentation for more information.

Webhook set up process

To set up a webhook subscription:

  1. Build a webhook receiver into your project. This is a URL that Nylas sends webhook payloads to.
  2. Make sure your project can respond to a verification request from Nylas with a 200 OK, within 10 seconds.
  3. Make sure you requested the correct authentication scopes for the webhook subscriptions, so that Nylas can access the items you want to monitor.
  4. Set up the webhook subscription in the Nylas Dashboard, by making an API request, or using the Nylas SDKs.
  5. Complete the verification by returning the exact value of the challenge parameter.

Respond to webhook verification request

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.

After the webhook is verified, Nylas generates a webhook_secret and sends updates to your application using webhook notifications.

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'}

Respond to webhooks

When the webhook is verified, Nylas generates a webhook_secret and uses it to send notifications to your application. Your application must respond to those updates with a 200 status code. If Nylas doesn't receive a response, it attempts 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 Nylas webhook signature

Every webhook notification that Nylas sends includes an X-Nylas-Signature header and the endpoint's HMAC-SHA256-encoded webhook_secret.

Retry attempts

Nylas tries sending failed webhook notifications up to five times, backing off exponentially. Nylas guarantees at least 4 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 you an email notification about the change.

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

Test webhooks

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

Webhook examples and sample applications

SDK examples and sample applications for v3 are coming soon.

Keep in mind

  • Webhooks are not compatible with Ngrok because of throughput limiting concerns.
  • 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 Nylas applications.
  • You should configure your webhook settings before you authenticate grants to your Nylas application.
  • Changes to webhook settings apply only to grants that connect after you save the changes.

More resources