Only show these results:

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:

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

Webhook Diagram 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

Anytime you create a webhook or set the state to active, Nylas will check to ensure your webhook is valid by making a GET request to your endpoint with a challenge query parameter. Your application needs to 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.
  • Ensure you are not returning anything other than the challenge parameter's exact value, 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': '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. 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.

API

To enable a webhook using the API, send a POST to https://api.nylas.com/a/{client_id}/webhooks.

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}(#notification-triggers). To see a triggers response examples and definitions, review Available Webhooks.
    • Basic Authentication where the username is the client_secret.
    POST /a/>cliient_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.

If you're using ngrok to test, Nylas limits the amount of data sent to these URLs. Nylas recommends using the CLI to test webhooks so that 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, we send an event.updated webhook. Event deleted webhooks are only sent when a syncback request fails. A failure can take a long time to come through. We recommend you use the event.updated webhook.

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 will send webhook notifications for historical messages, calendars, events, and contacts as it syncs the account data.

Retry Attempts

Nylas will retry failed webhook messages up to 5 times, backing off exponentially. We guarantee that we will make at least 4 retries within the first 20 minutes, and all 5 retries will occur within 1 hour. If we cannot make a successful POST request to your endpoint after 5 retries, we will skip that message and continue to send other webhook notifications.

Failed Webhooks

A webhook is marked as failing when:

  • We have received 95% non-200 responses over a period of 15 minutes.
  • We have received no response from the endpoint over a period of 15 minutes.

When this happens, we send an email notifying you of the failing webhook and change the webhook's state in our database to failing.

A webhook is marked as failed when:

  • We have received 95% non-200 responses (or non-responses) from the endpoint over a period of 3 days.
  • We have received no 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 a failed webhook is reactivated, it will send notifications for events from that point in time forward. It will not send notifications for any events that occurred while it was in the failed state. If your webhook reaches the failed state, you can reactivate it from the developer console.

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

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 IP address, the 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.

Historical Webhooks

Nylas lets you control which historical data triggers to send. Control messages, threads, calendar events, and contacts.

How Historical Webhooks Work

Webhooks are sent and controlled at the application level. This means any accounts you connect to your application will send webhooks. By default, when you connect an account, Nylas will send webhooks for data from and after the account connection date.

Using the Historical Webhooks settings, you can set a period to start receiving webhooks. There are 4 options.

  • Webhooks for data X days before account connection
  • Webhooks starting at account connection
  • Webhooks X days after account connection
  • Receive webhooks for all data

If you don't make any changes, the default setting is 0. Any newly connected accounts will only send data after the account is connected.

Existing Customers Historical Webhooks

If you already have an account set up with webhooks the behavior will not change. You will still continue to receive all webhooks.

Historical Webhooks Settings

Log in to your dashboard, choose the application you want to setup webhooks for, then click App Settings. On Settings, go to Application Product Settings and set the Number of days from account connection to send webhooks.

  • If you want webhooks 30 days before account connection, enter -30.
  • If you want webhooks starting from account connection, enter 0.
  • If you want webhooks 30 days after account connection, enter 30.
  • If you leave it blank, you will receive all hooks for all previous and new data.
Historical Webhooks Dashboard

Supported Objects

Object Sync Basis
Messages Received date
Thread Most recent received date. 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.
Event Non-recurring events only. Uses event end time, if the event end time is not available, uses the event start time.
Contacts Contacts that have been automatically created from an email will sync from the message received date. All other contacts have no restrictions for historical webhooks and you will still receive hooks for them, regardless of dashboard settings.

Keep in Mind

  • 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 adding accounts.
  • Webhook settings only apply to accounts connected after the settings are changed.

Best Practices

Use these suggestions to get the best experience using webhooks.

Asynchronous Processing

We strongly recommend processing webhook data asynchronously from ingested Nylas POST requests to avoid timeouts. Each request automatically times out after 10 seconds.

Enable Message Tracking

Use message tracking when sending emails to get webhooks when links are clicked, the emails are opened, or when someone replies.

Processing Historical Webhooks

Configure the hooks you want to get for newly connected accounts. The current default will only send webhooks for data received after the account is created.

If you expect to get a lot of webhooks, even with the default settings, we recommend spreading them over several hosts. Using several hosts will lessen the load and let you process webhooks quickly.

Sample Apps

Use our sample apps as a reference to start using webhooks.