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 the webhook version. |
[
{
"application_id": "8eejdhpc5dv04w6ea8lzlxtkt",
"callback_url": "https://97a5db5e7c59.ngrok.io/webhook",
"id": "7b5y8f25p344jy8yem6v5jir",
"state": "active",
"triggers": [
"account.connected",
"account.running",
"account.stopped",
"account.invalid",
"account.sync_error",
"message.created",
"message.opened",
"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"
],
"version": "2.0"
}
]
Webhook States
| State | Description |
|---|---|
active | We are sending data for this webhook and receiving 200 responses. |
inactive | The webhook has been disabled 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
When events are cancelled, you might expect to receive an event.deleted trigger. These types of events come through as event.updated. We only send event.deleted triggers when the object is deleted from Nylas' database.
| Attribute | Type | Description |
|---|---|---|
| deltas | array | An array consisting of a single delta object. |
| date | unix timestamp | A timestamp indicating when the change occurred. |
| object | string | The changed object type. Possible values are event.created, event.updated or event.deleted. |
| type | 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. |
| id | string | ID of the event. |
| metadata | null | Only applicable for message webhooks. |
{
"deltas": [
{
"date": 1601665341,
"object": "event",
"type": "event.created",
"object_data": {
"namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
"account_id": "aaz875kwuvxik6ku7pwkqp3ah",
"object": "event",
"attributes": null,
"id": "85iy1r26e1x79qtir27fr0nos",
"metadata": null
}
}
]
}
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. |
| object | string | The changed object type. Possible values are calendar.created, calendar.updated or calendar.deleted. |
| type | 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",
"object_data": {
"namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
"account_id": "aaz875kwuvxik6ku7pwkqp3ah",
"object": "calendar",
"attributes": null,
"id": "2x6fbv82cctfjqtzex0aqll96",
"metadata": null
}
}
]
}
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. |
| object | string | The changed object type. Possible values are account.running, account.stopped, account.invalid, account.connected. |
| type | 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. |
| object | string | The changed object type. Possible values are contact.created, contact.updated, contact.deleted. |
| type | 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
}
}
]
}
Message Webhooks
- 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.created. |
| type | 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. 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 Tracking
- message.opened
- message.link_clicked
- thread.replied
To learn more about, 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 object_data id 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 this will increase by one. message.opened` |
| 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
Message ID
When link tracking is enabled, the object_data id is the
message_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"
}
}
}
]
}
Updated 3 months ago