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

Nylas Python Webhook App

        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 a 400 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 the python-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': '[email protected]=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. The callback_url is the endpoint the Nylas servers send notifications to. The callback_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.
The callback_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

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

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.