Nylas Docs

Webhook Object

Attribute	Type	Description
`id`	string	A globally unique object identifier.
`application_id`	string	A reference to the parent application object.
`callback_url`	string	The URL where notifications are posted.
`state`	string	The state of the webhook. See the table below for possible values.
`triggers`	array	An array containing a set of triggers, describing the notifications this webhook should receive. See the triggers table for possible values.
`version`	string	A string describing the webhook version.

    [
        {
            "application_id": "8eejdhpc5dv04w6ea8lzlxtkt",
            "callback_url": "https://your-server.com/webhook",
            "id": "7b5y8f25p344jy8yem6v5jir",
            "state": "active",
            "triggers": [
                "account.connected",
                "account.running",
                "account.stopped",
                "account.invalid",
                "account.sync_error",
                "message.created",
                "message.opened",
                "message.updated",
                "message.link_clicked",
                "thread.replied",
                "contact.created",
                "contact.updated",
                "contact.deleted",
                "calendar.created",
                "calendar.updated",
                "calendar.deleted",
                "event.created",
                "event.updated",
                "event.deleted",
                "job.successful",
                "job.failed",
                "job.cancelled",
                "job.delayed"
            ],
            "version": "2.0"
        }
    ]

Minimum Required Scopes

Webhook triggers have corresponding minimum scopes. View the Nylas Scopes for the complete collection and the Authentication Scopes section for specific dependencies.

Webhook States

The state of a webhook displays its current status.

State	Description
`active`	We are sending data for this webhook and receiving `200` responses.
`inactive`	The webhook has been turned off from the developer console, and we are not sending data for this webhook.
`failing`	Webhooks are marked as failing when Nylas has received 95% non-200 responses (or non-responses) from the endpoint over a period of 15 minutes. When this happens, we send an email to the customer notifying them of the failing webhook, and change the webhook’s state in our database to failing. Read Failing Webhooks
`failed`	Webhooks are marked as failed when we have received 95% non-200 responses (or non-responses) from the endpoint over a period of 3 days. When this happens, we send an email to the customer notifying them of the failed webhook, and change the webhook’s state in our database to failed. Read Failed Webhooks for more.

Event Webhooks

event.created
event.updated
event.deleted

Attribute	Type	Description
`deltas`	array	An array consisting of a single delta object.
`date`	Unix timestamp	A timestamp indicating when the change occurred.
`type`	string	The changed object type. Possible values are `event.created`, `event.updated` or `event.deleted`.
`object`	string	The trigger for this notification.
`object_data`	object	This object contains the changed object's `object` type, `account_id`, object `id` and an `attributes` sub-object.
`namespace_id`	string	Deprecated field. Refer to the account ID.
`account_id`	string	ID of the connected email account.
`object`	string	The changed object type. Will return `event`.
`attributes`	null	Only applicable for message webhooks.
`attributes.created_before_account_connection`	null	Indicates if the event was created before the account was connected to Nylas. Only applicable for `event.created` or `event.updated`
`attributes.calendar_id`	null	Calendar ID of the event. Relates to the `created_before_account_connection`. Only applicable for `event.created` or `event.updated`
`id`	string	ID of the event.
`metadata`	null	Event metadata

{
 "deltas": [{
  "date": 1647532662,
  "object": "event",
  "type": "event.created", //can be event.created, event.updated, or event.deleted
  "object_data": {
   "namespace_id": "cct42fracyj4lv77loz8n3pd9",
   "account_id": "cct42fracyj4lv77loz8n3pd9",
   "object": "event",
   "attributes": {
    "created_before_account_connection": true, //only for created and updated events
    "calendar_id": 31243722414895696 // only for created and updated events
   },
   "id": "2ymvp6oqys6dqnilamlgly62j",
   "metadata": {
    "event-type": "Silver invoice",
    "message": "Hello Silver"
   }
  }
 }]
}

Event Updated Events

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.

We send an event.updated webhook when changes are made to the following fields. Review events for more information.

title
description
when
location
owner
participants
busy
recurrence
master_event_id
original_start_time

Calendar Webhooks

calendar.created
calendar.updated
calendar.deleted

Attribute	Type	Description
`deltas`	array	An array consisting of a single delta object.
`date`	Unix timestamp	A timestamp indicating when the change occurred.
`type`	string	The changed object type. Possible values are `calendar.created`, `calendar.updated` or `calendar.deleted`.
`object`	string	The trigger for this notification.
`object_data`	object	This object contains the changed object's `object` type, `account_id`, object `id` and an `attributes` sub-object.
`namespace_id`	string	Deprecated field. Refer to the account ID.
`account_id`	string	ID of the connected email account.
`object`	string	The changed object type. Will return `calendar`.
`attributes`	null	Only applicable for message webhooks.
`id`	string	ID of the calendar.
`metadata`	null	Only applicable for message webhooks.

    {
        "deltas": [
            {
                "date": 1601668428,
                "object": "calendar",
                "type": "calendar.updated", //can be calendar.created, calendar.updated, or calendar.deleted
                "object_data": {
                    "namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
                    "account_id": "aaz875kwuvxik6ku7pwkqp3ah",
                    "object": "calendar",
                    "attributes": null,
                    "id": "2x6fbv82cctfjqtzex0aqll96",
                    "metadata": null
                }
            }
        ]
    }

Calendar Updated Events

We send an calendar.updated webhook when changes are made to the following fields. Review calendar for more information.

description
is_primary
location
name
read_only
timezone

Account Webhooks

account.running
account.stopped
account.invalid
account.connected

Attribute	Type	Description
`deltas`	array	An array consisting of a single delta object.
`date`	Unix timestamp	A timestamp indicating when the change occurred.
`type`	string	The changed object type. Possible values are `account.running`, `account.stopped`, `account.invalid`, `account.connected`.
`object`	string	The trigger for this notification.
`object_data`	object	This object contains the changed object's `object` type, `account_id`, object `id` and an `attributes` sub-object.
`namespace_id`	string	Deprecated field. Refer to the account ID.
`account_id`	string	ID of the connected email account.
`object`	string	The changed object type. Will return `account`.
`attributes`	null	Only applicable for message webhooks.
`id`	string	ID of the webhook.
`metadata`	null	Only applicable for message webhooks.

    {
        "deltas": [
            {
                "date": 1601672445,
                "object": "account",
                "type": "account.running",
                "object_data": {
                    "namespace_id": "cg9razhjs80zqtoz50rox2n6z",
                    "account_id": "cg9razhjs80zqtoz50rox2n6z",
                    "object": "account",
                    "attributes": null,
                    "id": "cg9razhjs80zqtoz50rox2n6z",
                    "metadata": null
                }
            }
        ]
    }

Contact Webhooks

contact.created
contact.updated
contact.deleted

Attribute	Type	Description
`deltas`	array	An array consisting of a single delta object.
`date`	Unix timestamp	A timestamp indicating when the change occurred.
`type`	string	The changed object type. Possible values are `contact.created`, `contact.updated`, `contact.deleted`.
`object`	string	The trigger for this notification.
`object_data`	object	This object contains the changed object's `object` type, `account_id`, object `id` and an `attributes` sub-object.
`namespace_id`	string	Deprecated field. Refer to the account ID.
`account_id`	string	ID of the connected email account.
`object`	string	The changed object type. Will return `contact`.
`attributes`	null	Only applicable for message webhooks.
`id`	string	ID of the contact.
`metadata`	null	Only applicable for message webhooks.

    {
        "deltas": [
            {
                "date": 1601667544,
                "object": "contact",
                "type": "contact.updated",
                "object_data": {
                    "namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
                    "account_id": "aaz875kwuvxik6ku7pwkqp3ah",
                    "object": "contact",
                    "attributes": null,
                    "id": "1iacfgi0qcm28734iusgzo20o",
                    "metadata": null
                }
            }
        ]
    }

Contact Updated Events

We send an contact.updated webhook when changes are made to the following fields. Review contacts for more information.

given_name
middle_name
surname
suffix
nickname
birthday
company_name
job_title
manager_name
office_location
notes
picture_url
emails
im_addresses
physical_addresses
phone_numbers
web_pages
groups
source

Message Webhooks

message.created
message.updated

Message Created

Attribute	Type	Description
`deltas`	array	An array consisting of a single delta object.
`date`	Unix timestamp	A timestamp when the object was changed.
`object`	string	The changed object type. The value is `message`. .
`type`	string	The trigger type, `message.created`.
`object_data`	object	This object contains the changed object's `object` type, `account_id`, object `id` and an `attributes` sub-object.
`namespace_id`	string	Deprecated field. Refer to the account ID.
`account_id`	string	ID of the connected email account.
`object`	string	The changed object type. Possible values are `message` or `metadata`. Metadata will return when message tracking is enabled.
`attributes`	object	Attributes of the message.
`thread_id`	string	ID of the message thread.
`received_date`	Unix timestamp	Date the message was received. Nylas uses the email headers to determine this time.
`id`	string	ID of the message.
`metadata`	null	Message created returns null. Applicable for message tracking.

    {
        "deltas": [
            {
                "date": 1602623196,
                "object": "message",
                "type": "message.created",
                "object_data": {
                    "namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
                    "account_id": "aaz875kwuvxik6ku7pwkqp3ah",
                    "object": "message",
                    "attributes": {
                        "thread_id": "2u152dt4tnq9j61j8seg26ni6",
                        "received_date": 1602623166
                    },
                    "id": "93mgpjynqqu5fohl2dvv6ray7",
                    "metadata": null
                }
            }
        ]
    }

Message Updated Events

We send an message.updated webhook for the following event actions. Review messages for more information.

A message is starred or un-starred.
A message is set to read or unread.
A message is archived.
The message folder is changed. A message moved to the trash folder will trigger a message updated webhook. This does not mean the message has been deleted.
The message label is changed. A message with a trash label will trigger a message updated webhook. This does not mean the message has been deleted.
thread_id
subject
from
to
cc
bcc
reply_to
date
unread
starred
snippet
body
files
events

Attribute	Type	Description
`date`	Unix timestamp	Date and time the message was updated
`object`	string	The changed object.
`type`	string	The notification trigger. The value is `message.updated`.
`object_data`	object	This object contains the changed object's. sub-attributes.
`namespace_id`	string	Deprecated field. Refer to the account ID.
`account_id`	string	ID of the connected email account.
`object`	string	The changed object type. Will return `message`.
`attributes`	object	The attribute object
`attributes.thread_id`	string	Thread ID of the message.
`id`	string	ID of the message
`metadata`	string	Message updates returns null. Applicable for message tracking.

{
  "deltas": [
    {
      "date": 1640795044,
      "object": "message",
      "type": "message.updated",
      "object_data": {
        "namespace_id": "5tgncdmczat02216u7d6uypyi",
        "account_id": "5tgncdmczat02216u7d6uypyi",
        "object": "message",
        "attributes": {
          "thread_id": "4cixjtbijtxh06ai4413jfa23"
        },
        "id": "33lqorn5g0rgh0v8k3ge0fuyj",
        "metadata": null
      }
    }
  ]
}

Message Tracking

message.opened
message.link_clicked
thread.replied

To learn more about message tracking, read Message Tracking .

Message Opened

If you have message tracking enabled, you may get 2 notifications for opened messages.

Thread ID

When link tracking is enabled, the id value in the object_data is the thread_id.

Attribute	Type	Description
`metadata`	object	Contains metadata for message tracking
`count`	integer	Number of times the message was opened. The count starts at `1`. Each time the message is opened from `message.opened` this will increase by one .
`sender_app_id`	integer	Deprecated field.
`timestamp`	Unix timestamp	Indicates the time of the most recent change such as links clicked, message was opened or thread was replied to.
`recents`	array	An array of objects containing information about the most recent times the message was opened. Each time the message is opened a new object containing the `id` is added.
`ip`	string	IP address of the email that opened the message.
`id`	integer	Related to the count. While the count starts at `1`. The ID starts at `0`. Each time the message is opened this will increase by one.
`timestamp`	Unix timestamp	When the IP address opened the message.
`user_agent`	string	Information about the application, operating system and browser if available.
`payload`	string	A string you can supply as part of the message tracking payload.
`message_id`	string	ID of the message.

    {
        "deltas": [
            {
                "date": 1601655922,
                "object": "metadata",
                "type": "message.opened",
                "object_data": {
                    "namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
                    "account_id": "aaz875kwuvxik6ku7pwkqp3ah",
                    "object": "metadata",
                    "attributes": null,
                    "id": "2853jlwgcp70cufxakisb4kyx",
                    "metadata": {
                        "count": 2,
                        "sender_app_id": 64280,
                        "timestamp": 1601655922,
                        "recents": [
                            {
                                "ip": "46.502.7.144",
                                "user_agent": "Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)",
                                "timestamp": 1601655919,
                                "id": 0
                            },
                            {
                                "ip": "66.102.7.140",
                                "id": 1,
                                "timestamp": 1601655922,
                                "user_agent": "Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)"
                            }
                        ],
                        "message_id": "8ek8y0izenpumiuxs4gpp0dzq",
                        "payload": "Tracking enabled"
                    }
                }
            }
        ]
    }

Message Link Clicked

Thread ID

When link tracking is enabled, the object_data > id is the thread_id.

Attribute	Type	Description
`metadata`	object	Contains metadata for message tracking.
`sender_app_id`	integer	ID of your application in the Nylas database.
`link_data`	array	Array of objects with information about any links in the message. Link data and link index are related. The first object has a `link_index` of `0`. The second object in `link_data` has a `link_index` of `1`.
`url`	string	The URL.
`count`	integer	Number of times the link was clicked.
`timestamp`	Unix timestamp
`recents`	array	An array of objects containing information about the most recent times the message was opened. Each time the message is opened a new object containing the `id` is added.
`ip`	string	IP address of the email that opened the message.
`link_index`	integer	Link data and link index are related. The first object has a `link_index` of `0`. The second object in `link_data` has a link_index of `1`.
`id`	integer	Related to the count. While the count starts at `1`. The ID starts at `0`. Each time the message is opened this will increase by one. `message.opened`
`user_agent`	string	Information about the application, operating system and browser if available.
`timestamp`
`payload`	string	A string you can supply as part of the message tracking payload.
`message_id`	string	ID of the message.

    {
        "deltas": [
            {
                "date": 1602623989,
                "object": "metadata",
                "type": "message.link_clicked",
                "object_data": {
                    "namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
                    "account_id": "aaz875kwuvxik6ku7pwkqp3ah",
                    "object": "metadata",
                    "attributes": null,
                    "id": "740ktv6tse85fyfv3u8msazvg",
                    "metadata": {
                        "sender_app_id": 64280,
                        "link_data": [
                            {
                                "url": "https://google.com/",
                                "count": 1
                            },
                            {
                                "url": "https://nylas.com/",
                                "count": 1
                            }
                        ],
                        "timestamp": 1602623966,
                        "recents": [
                            {
                                "ip": "24.243.155.85",
                                "link_index": 0,
                                "id": 0,
                                "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.75 Safari/537.36",
                                "timestamp": 1602623980
                            },
                            {
                                "ip": "24.243.155.85",
                                "link_index": 1,
                                "id": 1,
                                "timestamp": 1602623989,
                                "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.75 Safari/537.36"
                            }
                        ],
                        "message_id": "4utnziee7bu2ohak56wfxe39p",
                        "payload": "Tracking enabled"
                    }
                }
            }
        ]
    }

Thread Replied

Thread ID

When link tracking is enabled, the object_data > id is the thread_id.

Attribute	Type	Description
`metadata`	object	Contains metadata for message tracking
`sender_app_id`	integer	ID of your application in the Nylas database.
`timestamp`	Unix timestamp	Time the thread was changed.
`from_self`	boolean	If the message sent is from the owner of the Nylas account.
`payload`	string	A string you can supply as part of the message tracking payload.
`thread_id`	string	ID of the message thread.
`reply_to_message_id`		ID of the message the thread is replying to.
`message_id`	string	ID of the message.

    {
        "deltas": [
            {
                "date": 1601656124,
                "object": "message",
                "type": "thread.replied",
                "object_data": {
                    "namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
                    "account_id": "aaz875kwuvxik6ku7pwkqp3ah",
                    "object": "message",
                    "attributes": null,
                    "id": "7sx8258vwi6xbmxljemm40f5c",
                    "metadata": {
                        "sender_app_id": 64280,
                        "timestamp": 1601656110,
                        "from_self": true,
                        "payload": "Tracking enabled",
                        "thread_id": "27dxbayb5z7s4bfpxkibby2c5",
                        "reply_to_message_id": "eea24ox0libvo0gwljyx8j4ou",
                        "message_id": "7sx8258vwi6xbmxljemm40f5c"
                    }
                }
            }
        ]
    }

Job Status Webhooks

job.successful
job.failed
job.delayed
job.cancelled

Attribute	Type	Description
`date`	Unix timestamp	A timestamp indicating when the change occurred.
`object`	string	The trigger for this notification. `job_status` for job status notifications.
`type`	string	The event status. Can be `job.successful`, `job.failed`, `job.delayed`, `job.cancelled`.
`object_data`	object	This object contains the changed object's `object` information.
`object_data.namespace_id`	string	Deprecated field. Refer to the account ID.
`object_data.account_id`	string	ID of the connected email account.
`object_data.object`	string	The changed object type. Can be `messages`, `calendar`, `folders`, or`labels`.
`object_data.attributes`	object	Attributes of the message.
`object_data.attributes.action`	text	Event that triggered the job status webhook. Can be `create_calendar`, `update_calendar`, `delete_calendar`, `create_contact`, `update_contact`, `delete_contact`, `create_folder`, `update_folder`, `delete_folder`, `create_label`, `update_label`, `create_event`, `update_event`, `delete_event`, `update_message`, `save_draft`, `new_outbox`.
`object_data.attributes.thread_id`	string	Thread ID of the message. Returns when using Outbox.
`object_data.attributes.message_id`	string	ID of the message associated with the Job.
`object_data.attributes.job_status_id`	string	ID of the job.
`object_data.attributes.extras`	object	If the job_status has a status of cancelled, delayed, or failed then extras returns in the response with more information.
`object_data.attributes.extras.reason`	string	Reason for status
`object_data.attributes.extras.original_send_at`	integer	Unix timestamp assigned from sending a message. This value reflects the initial attempt for sending. Updates to Outbox `send_at` values also change this value.
`object_data.attributes.extras.send_at`	integer	Unix timestamp for when the message was sent.
`id`	string	A globally unique object identifier.
`metadata`	null	Message created returns null. Applicable for message tracking.

{
    "deltas": [
        {
            "date": 1646346505,
            "object": "job_status",
            "type": "job.cancelled",
            "object_data": {
                "namespace_id": "mmTT7dLRPxbZwZTNTWIFjGQbJk",
                "account_id": "mmTT7dLRPxbZwZTNTWIFjGQbJk",
                "object": "message",
                "attributes": {
                    "action": "new_outbox",
                    "thread_id": null,
                    "message_id": null,
                    "job_status_id": "C2op6GEHMYkehv8k9BV2ovfgsM"
                },
                "id": null,
                "metadata": null
            }
        }
    ]
}