Set up webhooks
Webhooks allow your application to receive notifications when certain events occur. For example, when a new email is received, Nylas will make a POST request to your callback_url
endpoint, letting you know about the new message. You can specify what events you'd like to be notified about in the developer dashboard or with the Webhooks API.
Webhooks are the recommended way to get notified of changes to the accounts you sync because they can easily integrate with your app and scale seamlessly with your growth.
Prerequisites
To start using webhooks, you need:
- An application that can respond to the verification request with a
200 OK
. - Enable the webhook using either the Nylas Developer Dashboard or the webhook endpoint.
- Configure your data and webhook sync.
- Make sure you have the right Authentication Scopes for your webhooks.
Webhook Starters
Check out the Node.js, Ruby, Python ,and Java example projects to see how to start accepting notifications from Nylas.
How Webhooks Work with Nylas

Let's go over a general workflow for using webhooks.
The first time you create a webhook or set the state to active, Nylas will check that the webhook is valid by a GET request to your endpoint with a challenge query parameter. Your application must return the exact value of the challenge query parameter in the body of the response.
If you fail to return a response within 10 seconds, Nylas will return a 400 BAD REQUEST
. Nylas will not attempt to verify the webhook again.
Once you have your webhooks created, Nylas will send updates to your app, and you must respond with a 200 response. If you don't, Nylas will attempt 5 more times before changing the status to failing.
Every webhook from Nylas includes an X-Nylas-Signature
header. You can use this to verify that the data is coming from Nylas.
Authorization
Webhooks use Basic Authentication. Use the application client_secret
.
Authorization Example
is_genuine = verify_signature(
message=request.data,
key=app.config["NYLAS_OAUTH_CLIENT_SECRET"].encode("utf8"),
signature=request.headers.get("X-Nylas-Signature"),
)
if not is_genuine:
return "Signature verification failed!", 401
Authentication Scopes
Nylas Scopes are required to make API requests through Nylas and are dependencies for creating webhook notifications. Each notification trigger has corresponding minimum scopes.
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 |
Challenge parameter
Any time you create a webhook or set a webhook's state to active
, Nylas makes a GET request to your endpoint with a challenge
query parameter to check that your webhook is valid. Your application must return the exact value of the challenge
query parameter in the response body.
- Your application has up to 10 seconds to respond to the verification request.
The verification request is not retried if it fails the first check. If your application does not respond to the verification, Nylas returns a400 BAD REQUEST
error. - Only return the challenge parameter's exact value. Do not include anything else, not even quotation marks.
- Do not use chunked encoding in response to the GET.
- Allow the
USER-AGENT
header with thepython-requests
value. Without this field, applications may discard inbound API requests.
View the example challenge request below. This sample adds line breaks to separate the header fields for visibility.
{'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'}
Responding to Webhooks
You can respond to webhooks using 200-299 response codes.
Verify Nylas Webhooks
Each webhook includes an X-Nylas-Signature
header. The header contains a hex-encoded HMAC-SHA256 signature of the request body, using your client secret as the signing key. Using the header allows your application to verify that the notification came from Nylas.
The signature is for the exact content of the request body. Make sure that your processing code does not modify the body before checking the signature.
The body of the request is in the UTF-8 JSON format and contains details about the event.
Scheduler webhooks do not include the X-Nylas-Signature
header.
Create Webhooks
Webhooks for an application are configured either from the Nylas Developer Dashboard or programmatically using a POST request to the webhooks endpoint.
Nylas Dashboard
To configure a new webhook using the dashboard, go to the Webhooks section of your application and select the webhooks you want to add.
You will need to provide:
- The full
callback_url
for the webhook. Thecallback_url
is the endpoint the Nylas servers send notifications to. Thecallback_url
must be accessible from the public internet for the webhook to work. It must be an HTTPS endpoint as well. The endpoint is verified by sending a verification request. - The notification triggers. To see triggers response examples and definitions, review Available Webhooks.
Webhooks API
To enable a webhook using the API, send a POST to https://api.nylas.com/a/{client_id}/webhooks
.
You must provide:
- The full
callback_url
for the webhook.
Thecallback_url
is the endpoint the Nylas servers send notifications to, and must be an HTTPS endpoint, accessible from the public internet, for the webhook to work. The endpoint is verified by sending a verification request. - The notification triggers.
See Available Webhooks for trigger response examples and definitions. - Basic Authentication, where the username is the
client_secret
.
POST /a/>client_id>/webhooks HTTP/1.1
Host: api.nylas.com
Authorization: Basic <client_secret>
Content-Type: application/json
{
"callback_url": "https://your-server.com/webook",
"triggers": [
"message.opened",
"contact.created"
],
"state": "active"
}
Testing webhooks
Tip! The Nylas SDKs include tools to allow you to test webhooks locally. See the pages for Node.js, Ruby, Python, and Java for more information.
You can also launch a server using the Nylas CLI to listen to incoming Nylas webhook events. The tunnel
command maintains a server for two hours and can restart an unlimited number of times. View the Using Webhooks guide for more information.
Nylas limits the amount of data sent to ngrok
testing URLs. You should use the Nylas CLI to test webhooks to ensure you receive all data during testing and development.
Notification triggers
Trigger | Description |
---|---|
account.connected |
An account has been connected to your app. |
account.invalid |
An account has invalid credentials and must re-authenticate. |
account.running |
An account is syncing and running properly even if the account is in a partial state. |
account.stopped |
An account was stopped or cancelled. |
account.sync_error |
An account has a sync error and is no longer syncing. |
message.created |
A new message was sent or received. |
message.link_clicked |
A link in a tracked message has been clicked by a message participant. Enable using Message Tracking. |
message.opened |
A tracked message has been opened by a message participant. Enable using Message Tracking. |
message.updated |
An update to a message occurred. |
thread.replied |
A participant replied to a tracked thread. |
contact.created |
A contact has been added to an account. |
contact.updated |
A contact has been updated on an account. |
contact.deleted |
A contact has been deleted from an account. |
calendar.created |
A calendar has been added to an account. |
calendar.updated |
A calendar has been updated on an account. |
calendar.deleted |
A calendar has been deleted from an account. |
event.created |
An event has been added to an account. |
event.updated |
An event has been updated on an account. This can include event changes and event deletions. |
event.deleted |
An event has been deleted from an account. |
job.successful |
Job was successfully synced back to the provider for a given job_status_id. |
job.failed |
The job has permanently failed after retrying 20 times. The changes have not synced with the provider. |
Event Update and Delete
When events are canceled or deleted from a calendar, Nylas sends an event.updated
webhook.
Event deleted webhooks are only sent when a sync-back request fails. A failure can take a long time to come through, so you should use the event.updated
webhook instead.
Email Tracking Notifications
If you have message tracking enabled, you may get 2 notifications for opened messages.
Newly Connected Accounts
When a new account is connected, Nylas sends webhook notifications for historical messages, calendars, events, and contacts as it syncs the account data.
Retry attempts
Nylas retries failed webhook messages up to five times, backing off exponentially. Nylas guarantees at least four retries within the first 20 minutes, and all five retries will occur within 1 hour. If Nylas cannot make a successful POST request to your endpoint after 5 retries, the system skips that message and continues to send other webhook notifications.
Failed Webhooks
A webhook is marked as failing when:
- Nylas receives 95% non-200 responses over a period of 15 minutes.
- Nylas does not receive any response from the endpoint over a period of 15 minutes.
When this happens, Nylas sends an email notification and changes the webhook's state to failing.
A webhook is marked as failed when:
- Nylas receives 95% non-200 responses (or non-responses) from the endpoint over a period of 3 days.
- Nylas does not receive a response from the endpoint over a period of 3 days.
You can reactivate through the Nylas dashboard or by using the webhook endpoint.
Reactivated failed webhooks
When you reactivate a failed webhook, the webhook starts sending notifications from that point in time forward. It does not send notifications for events that occurred while it was marked as failed.
Notification format
Nylas sends out payloads that contain the details of a single change. For security reasons, payloads don't include the details of the change. Instead, they have the trigger type and object ID for each change. You can use this data to query the appropriate Nylas API endpoint to get the object's details.
Learn More
For examples of Webhook Objects, view the Available Webhooks page.
Message created format example
{
"deltas": [
{
"date": 1601654025,
"object": "message",
"type": "message.created",
"object_data": {
"namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
"account_id": "aaz875kwuvxik6ku7pwkqp3ah",
"object": "message",
"attributes": {
"thread_id": "52yua3vyqlu8qzxptl60rfyd9",
"received_date": 1601654026
},
"id": "67il0blaili658hdc6u1zt80w",
"metadata": null
}
}
]
}
Keep in mind that in some cases, the attributes
can have a value of None
when messages are deleted.
Message tracking
Use message tracking to get webhooks when a message is:
- Opened
- Replied to
- Link is clicked
Read more about Message Tracking.
Enable and disable webhooks
Webhooks are set to active by default. To disable a webhook, go to the Webhooks section of your application and change the webhook's state to inactive. You can also make a PUT request to /webhook/{id} to set the state.
When you pause a webhook, it stops sending all events. When you reactivate the webhook, it starts sending data from date of reactivation. Webhooks are not sent for data when it was paused.
If you need to modify the callback_url
or triggers for your webhook, please make a new POST request.
Allowlist IP Addresses
If you need to allowlist an IP address that sends webhooks, the Nylas IP Addresses endpoint returns a list of dynamic IP addresses.
Multiple Webhooks
You can create more than one webhook for your application, but the webhook endpoints can not be the same. For example, you may create a webhook to receive notifications for the message.created
trigger, and another to receive notifications for the account.connected and account.stopped
triggers, but the webhooks must have different callback URIs.
Keep in Mind
- Email threads can be incomplete if the sync date is not far enough in the past. Make sure to sync to the start of the threads.
- Historical Webhook settings only apply to new applications.
- You should configure your webhook settings before you add accounts.
- Changes to webhook settings only apply to accounts that connect after you save the changes.