Nylas Webhook Notifications API
Your application receives information about changes to user accounts and data through Nylas webhooks. 🔍 The term "webhook" can refer to any of three component parts: a location where you receive notifications (the "webhook URL" or "webhook endpoint"), a subscription to events that you want notifications for ("webhook triggers"), or the information payload that is sent when a trigger condition is met (the "webhook notification"). We try to be specific in this documentation to avoid confusion. To configure webhooks, you first need a webhook URL in your project where your app can receive incoming webhook payloads, and a list of triggers that you want to receive notifications for. See the [list of available trigger types](/docs/reference/notifications/) for more information. Webhooks in Nylas are not compatible with Ngrok because of throughput limiting concerns. Nylas recommends you use [VS Code port forwarding](https://code.visualstudio.com/docs/editor/port-forwarding), [Hookdeck](https://hookdeck.com/), or a similar webhook tool. ## Testing webhooks Nylas includes two utility API endpoints to help you identify problems with your webhook configuration. Use the [Send Test Event endpoint](/docs/reference/api/webhook-notifications/send_test_event/) to check if your project's webhook destination is configured correctly. This endpoint sends a test webhook payload, and listens for a success acknowledgement from the webhook destination. Use the [Get Mock Notification Payload endpoint](/docs/reference/api/webhook-notifications/get_mock_webhook_payload/) to see example notification payloads for the different Nylas events. ## Monitor grant status The most important webhooks to subscribe to are those related to grant status: `grant.created`, `grant.updated`, `grant.deleted`, and `grant.expired`. They allow you to automate important grant lifecycle processes, like onboarding messages, data refreshes, and backend deletions. The `grant.expired` trigger notifies you when a user needs to re-authenticate their account. When you receive a `grant.expired` notification, you can take appropriate action (for example, notifying the user or starting a background re-authentication process). 📝 When a grant becomes invalid, Nylas cannot access the user's data and does not send you webhook notifications about it. When you re-authenticate a grant, Nylas looks at when the grant last authenticated successfully. If it was less than 72 hours ago, Nylas looks for any changes that happened since the time of the last successful sync, and sends you notifications about them. This can be a lot of notifications. If the grant has been out of service for more than 72 hours, Nylas does _not_ send backfill notifications. In this case, look for the `grant.expired` and `grant.updated` notifications, and query the Nylas API for objects that changed between those timestamps. ## iCloud limitation for Calendar notifications Because iCloud doesn't support the `primary` property for calendars, Nylas sends `calendar.updated` notifications for changes to all calendars on an iCloud account. ## Gmail metadata notifications Nylas sends [`message.created.metadata` and `message.updated.metadata` notifications](/docs/reference/notifications/#message-metadata-notifications) for Google grants that include the `/gmail.metadata` scope. These notifications have limited data because of the restrictive scope. Even if a grant has more permissive scopes, Google falls back to the `/gmail.metadata` permissions. When you subscribe to a `message.*` webhook trigger, Nylas automatically sends `message.*.metadata` notifications as well. You don't need to subscribe to these triggers separately, and they don't appear as a configuration option in the Nylas Dashboard. For more information, see our list of [available trigger types](/docs/reference/notifications/). ## Payload size limit and truncation Nylas sends webhook notifications as JSON payloads that contain the object that triggered the notification, up to a maximum payload size of 1MB. If a webhook notification exceeds the size limit, Nylas truncates the payload by removing the body content, and adds the `.truncated` suffix to the webhook trigger name (for example, `message.created.truncated`). This reduces the size of the payload and improves performance. When you receive a truncated webhook notification, you'll need to re-query the Nylas APIs to get the data. For example, if you receive a `message.updated.truncated` notification, make a [Get Message request](/docs/reference/api/messages/get-messages-id/) that includes the message ID. If you subscribe to a webhook trigger that can be truncated, Nylas automatically sends you `.truncated` notifications as well. You don't need to subscribe to webhook triggers with the `.truncated` suffix separately, and the suffix doesn't appear as a option in the Nylas Dashboard. See the [list of available trigger types](/docs/reference/notifications/) for more information. You can monitor for `.truncated` notifications to create automations that retrieve the full affected object. For example, you can create an automation that makes a [`GET /v3/grants//messages/` request](/docs/reference/api/messages/get-messages-id/) when your application receives a `message.updated.truncated` notification. ## Payload compression Set `compressed_delivery` to `true` on a webhook destination and Nylas gzip-compresses each notification before `POST`ing it to your endpoint, adding a `Content-Encoding: gzip` header. Compressed payloads are also opaque to firewalls and WAFs that would otherwise block requests containing HTML in email bodies. Verify the `X-Nylas-Signature` header against the raw compressed body _before_ decompressing. For full setup and when to use it, see [Reducing payload size with compression](/docs/dev-guide/best-practices/compression/). ## How to handle webhook failures Nylas implements "circuit breaker" logic to handle failing webhooks. See [improvements to failure notifications](/docs/new/in-v3/webhooks-changes/#improvements-to-webhook-failure-notifications) and [Failing and failed webhooks](/docs/v3/notifications/#failing-and-failed-webhooks) for more information. - **Failing state**: If Nylas cannot deliver a webhook notification to the destination endpoint for 95% of webhooks over a 15-minute period, Nylas marks the endpoint as `failing` but continues sending notifications to it. Nylas also sends you a message when this happens so you can troubleshoot the issue. - **Failed state**: If Nylas cannot deliver 95% of webhook notifications to a `failing` endpoint over the next 72 hours, Nylas marks the endpoint as `failed` and stops sending notifications to it. Nylas also sends you a message when this happens so you can address the issue. ⚠️ Nylas does not automatically restart or reactivate failed webhooks. This change gives you full control over when your webhook endpoint becomes active again, so you can verify that it's working as expected before you restart normal webhook traffic. ## Duplicate webhook notifications Nylas guarantees "at least once" delivery of webhooks. You might receive duplicate webhook notifications because of the provider's behavior (for example, when Google and Microsoft Graph send upserts). ## Webhook triggers - `contact.updated`: A contact was modified or updated. - `contact.deleted`: A contact was deleted. - `calendar.created`: A calendar was created. - `calendar.updated`: A calendar was updated or modified. - `calendar.deleted`: A calendar was deleted. - `event.created`: An event was created on a user's calendar. - `event.updated`: An event was updated or modified. - `event.deleted`: An event was deleted. - `grant.created`: A new grant was authenticated. - `grant.updated`: A grant was modified, updated, or re-authenticated. - `grant.deleted`: A grant was deleted as a result of the user making a [Delete Grant request](/docs/reference/api/manage-grants/delete_grant_by_id/). - `grant.expired`: A grant's credentials have expired, and the user must re-authenticate. - `message.created`: A message was created. - `message.created.cleaned`: A cleaned (parsed) version of a newly created message was processed. Requires Clean Conversations to be enabled. - `message.updated`: A message was updated. - `message.send_success`: A scheduled message was sent and delivered successfully. You must set the `send_at` parameter in a message to use this trigger. For more information, see [Schedule messages to send in the future](/docs/v3/email/scheduled-send/). - `message.send_failed`: A scheduled message was sent, but was not delivered. You must set the `send_at` parameter in a message to use this trigger. For more information, see [Schedule messages to send in the future](/docs/v3/email/scheduled-send/). - `message.bounce_detected`: (Available for Google, Microsoft Graph, iCloud, and Yahoo) A message bounced or was not delivered. - `message.opened`, `message.opened.legacy`: A participant opened a tracked message. - `message.link_clicked`, `message.link_clicked.legacy`: A participant clicked a link in a tracked message. - `thread.replied`, `thread.replied.legacy`: A participant replied to a message in a tracked thread. - `folder.created`: A folder or label was created. - `folder.updated`: A folder or label was modified or updated. - `folder.deleted`: A folder or label was deleted. - `booking.created`: A new Scheduler event was created. - `booking.rescheduled`: A Scheduler event was rescheduled through Scheduler. - `booking.cancelled`: A Scheduler event was cancelled through the Scheduler. - `booking.pending`: A pending booking was created. - `booking.reminder`: Nylas sent a reminder about a booking. For more information on webhook trigger types, and for schema examples, see the [notification schemas](/docs/reference/notifications/). ## Scheduler events in Calendar webhooks Calendar events that Nylas Scheduler creates also produce standard `event.*` notifications. Nylas stamps these events with metadata so you can identify them in Calendar webhooks: - `source`: Always `scheduler`. - `key5`: The Scheduler Configuration ID. - `scheduler_last_start`, `scheduler_last_end`, `scheduler_updated_at`: Unix timestamps (as strings) that record the meeting time Scheduler most recently set, at booking creation and on each reschedule. To tell Scheduler-driven changes apart from edits made directly on the organizer's calendar, compare an `event.updated` notification's `when` times against `scheduler_last_start` and `scheduler_last_end`: if the times match, the change came through Scheduler (Nylas also sends a `booking.rescheduled` notification), and if they differ, the event was changed directly on the calendar. These metadata entries share the event's customer-visible `metadata` object. If you update an event's metadata using the Events API, include the Scheduler-stamped entries in your request — updates replace the metadata object as a whole.
POST
/v3/webhooks
Create a webhook destination
#
GET
/v3/webhooks
Get destinations for an application
#
GET
/v3/webhooks/{id}
Get the destinations for an application by webhook ID
#
PUT
/v3/webhooks/{id}
Update a webhook destination
#
DELETE
/v3/webhooks/{id}
Delete a webhook destination
#
POST
/v3/webhooks/rotate-secret/{id}
Rotate a webhook secret
#
POST
/v3/webhooks/mock-payload
Get mock notification payload
#
POST
/v3/webhooks/send-test-event
Send test event
#
Documentation
Specifications
Other Resources
Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Nylas Webhook Notifications API
version: v3
summary: The complete Nylas v3 API — Email, Calendar, Contacts, Notetaker, Scheduling, Administration, and Migration.
description: The Nylas API is designed using the REST ideology to provide simple and predictable URIs to access and modify objects.
contact:
url: https://www.nylas.com/
x-provenance:
method: harvested
first_party: true
publisher: Nylas
source: https://developer.nylas.com/_spec-files/nylas-api.yaml
harvested: '2026-08-21'
sha256: 7ff001d571e163b1ffe22178741b59f813d8208ec878157a839a33dc2c13fd35
bytes: 1666223
note: 'Published by Nylas as the unified contract for the Nylas v3 API and stored verbatim; API Evangelist added only this provenance block. Submitted by the provider in api-evangelist/nylas#1 and verified against the live URL before harvest: OpenAPI 3.1.0, 118 paths, 208 operations, 174 component schemas, 100% of operations carrying summary, description, tag and a unique operationId, x-code-samples on 208 of 208. This document REPLACES a 22-operation scaffold API Evangelist derived from reading the documentation, now quarantined under openapi/_scaffold/.'
x-evidence:
- url: https://developer.nylas.com/_spec-files/nylas-api.yaml
what: the published unified contract, harvested verbatim 2026-08-21 (200, text/yaml, 1,666,223 bytes)
- url: https://developer.nylas.com/.well-known/api-catalog
what: RFC 9727 linkset advertising that URL as service-desc for api.us.nylas.com and api.eu.nylas.com (200, application/linkset+json)
servers:
- url: https://api.us.nylas.com
description: U.S.
- url: https://api.eu.nylas.com
description: E.U.
security:
- ACCESS_TOKEN: []
- NYLAS_API_KEY: []
tags:
- name: Webhook Notifications
description: Your application receives information about changes to user accounts and data through Nylas webhooks.
paths:
/v3/webhooks:
post:
tags:
- Webhook Notifications
summary: Create a webhook destination
operationId: post-webhook-destinations
description: 'Creates a webhook destination with the specified URL and list of trigger types.
### Webhook destinations and retry logic
You should limit the number of webhook destinations you have for each trigger type. When Nylas
retries a webhook, the retry goes to all the destinations for that trigger type. This can result
in _a lot_ of notifications.
Some webhook testing tools rate-limit or block you if your endpoint generates too much traffic.
Nylas blocks Ngrok connections for this reason.
### Webhook notification header
Every webhook notification Nylas sends includes the `x-nylas-signature` header. If you''re using
the Nylas SDKs, you might see `X-Nylas-Signature` instead.'
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/create_200'
description: Returns the new Destination
'400':
$ref: '#/components/responses/create_400'
requestBody:
required: true
description: Destination definition
content:
application/json:
schema:
$ref: '#/components/schemas/destination_input_payload'
x-code-samples:
- lang: bash
label: cURL
source: "curl --request POST \\\n --url 'https://api.us.nylas.com/v3/webhooks/' \\\n --header 'Content-Type: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data-raw '{\n \"trigger_types\": [\n \"grant.created\",\n \"grant.deleted\",\n \"grant.expired\"\n ],\n \"description\": \"local\",\n \"webhook_url\": \"<WEBHOOK_URL>\",\n \"notification_email_addresses\": [\n \"leyah@example.com\",\n \"nyla@example.com\"\n ]\n }'"
- lang: javascript
label: Node.js SDK
source: "import Nylas, { WebhookTriggers } from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst createWebhook = async () => {\n try {\n const webhook = await nylas.webhooks.create({\n requestBody: {\n triggerTypes: [WebhookTriggers.EventCreated],\n webhookUrl: \"<WEBHOOK_URL>\",\n description: \"My first webhook\",\n notificationEmailAddresses: [\"<EMAIL_ADDRESS>\"],\n },\n });\n\n console.log(\"Webhook created:\", webhook);\n } catch (error) {\n console.error(\"Error creating webhook:\", error);\n }\n};\n\ncreateWebhook();\n"
- lang: python
label: Python SDK
source: "from nylas import Client\nfrom nylas.models.webhooks import WebhookTriggers\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nwebhook = nylas.webhooks.create(\n request_body={\n \"trigger_types\": [WebhookTriggers.EVENT_CREATED],\n \"webhook_url\": \"<WEBHOOK_URL>\",\n \"description\": \"My first webhook\",\n \"notification_email_addresses\": [\"<EMAIL_ADDRESS>\"],\n }\n)\n\nprint(webhook)\n"
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\n\nnylas = Nylas::Client.new(api_key: \"<NYLAS_API_KEY>\")\n\nrequest_body = {\n trigger_types: [Nylas::WebhookTrigger::EVENT_CREATED],\n webhook_url: \"<WEBHOOK_URL>\",\n description: 'My first webhook',\n notification_email_addresses: [\"<EMAIL_ADDRESS>\"]\n}\n\nbegin\n webhook, _request_id = nylas.webhooks.create(request_body: request_body)\n\n puts \"Webhook created: #{webhook}\"\nrescue Nylas::NylasApiError => e\n puts \"Error creating webhook: #{e.message}\"\nend\n"
- lang: java
label: Java SDK
source: "import com.nylas.NylasClient;\nimport com.nylas.models.*;\nimport java.util.ArrayList;\nimport java.util.List;\n\npublic class webhooks {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n List<WebhookTriggers> triggers = new ArrayList<>();\n triggers.add(WebhookTriggers.EVENT_CREATED);\n\n CreateWebhookRequest webhookRequest = new CreateWebhookRequest(\n triggers,\n \"<WEBHOOK_URL>\",\n \"My first webhook\",\n List.of(\"<EMAIL_ADDRESS>\"));\n\n try {\n Response<WebhookWithSecret> webhook = nylas.webhooks().create(webhookRequest);\n\n System.out.println(webhook.getData());\n } catch (Exception e) {\n System.out.println(\"Error: \" + e);\n }\n }\n}\n"
- lang: kotlin
label: Kotlin SDK
source: "import com.nylas.NylasClient\nimport com.nylas.models.*\n\nfun main(args: Array<String>){\n val nylas: NylasClient = NylasClient(apiKey = \"<NYLAS_API_KEY>\")\n val triggersList: List<WebhookTriggers> = listOf(WebhookTriggers.EVENT_CREATED)\n\n val webhookRequest: CreateWebhookRequest = CreateWebhookRequest(\n triggersList,\n \"<WEBHOOK_URL>\",\n \"My first webhook\",\n listOf(\"<EMAIL_ADDRESS>\"))\n\n try {\n val webhook: Response<WebhookWithSecret> = nylas.webhooks().create(webhookRequest)\n\n println(webhook.data)\n } catch(exception : Exception) {\n println(\"Error :$exception\")\n }\n}\n"
get:
tags:
- Webhook Notifications
summary: Get destinations for an application
operationId: get-webhook-destinations-application
description: Get a list of all webhook destinations for an application id.
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/get_200'
description: List of destinations for an application.
'400':
$ref: '#/components/responses/get_400'
x-code-samples:
- lang: bash
label: cURL
source: "curl --request GET \\\n --url 'https://api.us.nylas.com/v3/webhooks' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
- lang: javascript
label: Node.js SDK
source: "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst listWebhooks = async () => {\n try {\n const webhooks = await nylas.webhooks.list({});\n\n console.log(\"webhooks:\", webhooks);\n } catch (error) {\n console.error(\"Error fetching webhooks:\", error);\n }\n};\n\nlistWebhooks();\n"
- lang: python
label: Python SDK
source: "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nwebhooks = nylas.webhooks.list()\n\nprint(\"webhooks:\", webhooks)\n"
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nwebhooks = nylas.webhooks.list()\nputs webhooks\n"
- lang: java
label: Java SDK
source: "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class webhooks {\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n ListResponse<Webhook> webhooks = nylas.webhooks().list();\n System.out.println(webhooks.getData());\n }\n}\n"
- lang: kotlin
label: Kotlin SDK
source: "import com.nylas.NylasClient\n\nfun main(args: Array<String>){\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val webhooks = nylas.webhooks().list()\n println(webhooks.data)\n}\n"
/v3/webhooks/{id}:
get:
operationId: get-webhook-by-id
tags:
- Webhook Notifications
summary: Get the destinations for an application by webhook ID
description: Get the webhook destinations for an application ID by webhook ID
security:
- NYLAS_API_KEY: []
parameters:
- name: id
in: path
schema:
type: string
required: true
responses:
'200':
$ref: '#/components/responses/get_by_id_200'
description: The destinations matching the query
'400':
$ref: '#/components/responses/get_400'
x-code-samples:
- lang: bash
label: cURL
source: "curl --request GET \\\n --url 'https://api.us.nylas.com/v3/webhooks/<WEBHOOK_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
- lang: javascript
label: Node.js SDK
source: "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function fetchWebhookById() {\n try {\n const webhook = await nylas.webhooks.find({\n webhookId: \"<WEBHOOK_ID>\",\n });\n\n console.log(\"webhook:\", webhook);\n } catch (error) {\n console.error(\"Error fetching webhook:\", error);\n }\n}\n\nfetchWebhookById();\n"
- lang: python
label: Python SDK
source: "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nmessage = nylas.webhooks.find(\n \"<WEBHOOK_ID>\",\n)\n\nprint(message)\n"
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nwebhook = nylas.webhooks.find(webhook_id: \"<WEBHOOK_ID>\")\nputs webhook\n"
- lang: java
label: Java SDK
source: "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class webhooks {\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n Response<Webhook> webhook = nylas.webhooks().find(\"<WEBHOOK_ID>\");\n System.out.println(webhook.getData());\n }\n}\n"
- lang: kotlin
label: Kotlin SDK
source: "import com.nylas.NylasClient\n\nfun main(args: Array<String>){\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val webhooks = nylas.webhooks().find(\"<WEBHOOK_ID>\")\n println(webhooks.data)\n}\n"
put:
operationId: put-webhook-by-id
tags:
- Webhook Notifications
summary: Update a webhook destination
description: 'Update the values in a specific webhook destination.
### Limitations
- You only need to specify fields that need to change when you make a request to this endpoint.
Empty fields in the request do not overwrite existing fields.
- You should limit how many webhook destinations you have for each trigger type. When Nylas retries
a webhook, the retry goes to _all destinations for the specific trigger type_. This can result in
a lot of notifications.
- Some webhook testing tools rate-limit or block you if your webhook destination endpoint generates
too much traffic. Nylas blocks Ngrok connections for this reason.'
security:
- NYLAS_API_KEY: []
parameters:
- name: id
in: path
schema:
type: string
required: true
responses:
'200':
$ref: '#/components/responses/update_200'
'400':
$ref: '#/components/responses/update_400'
requestBody:
required: true
description: Destination definition
content:
application/json:
schema:
$ref: '#/components/schemas/destination_update_payload'
x-code-samples:
- lang: bash
label: cURL
source: "curl --request PUT \\\n --url 'https://api.us.nylas.com/v3/webhooks/<WEBHOOK_ID>' \\ \n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data '{\n \"notification_email_addresses\": [\"leyah@example.com\"]\n }'"
- lang: javascript
label: Node.js SDK
source: "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function updateWebhook() {\n try {\n const webhook = await nylas.webhooks.update({\n webhookId: \"<WEBHOOK_ID>\",\n requestBody: {\n notificationEmailAddresses: [\"<EMAIL_ADDRESS>\"],\n },\n });\n\n console.log(\"Updated Webhook:\", webhook);\n } catch (error) {\n console.error(\"Error updating webhook:\", error);\n }\n}\n\nupdateWebhook();\n"
- lang: python
label: Python SDK
source: "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nwebhook = nylas.webhooks.update(\n \"<WEBHOOK_ID>\",\n request_body={\n \"notification_email_addresses\": [\"<EMAIL_ADDRESS>\"],\n }\n)\n\nprint(webhook)\n"
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nrequest_body = {\n description: 'My updated webhook'\n}\n\nwebhooks = nylas.webhooks.update(webhook_id: \"<WEBHOOK_ID>\", \nrequest_body: request_body)\nputs webhooks\n"
- lang: java
label: Java SDK
source: "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class webhooks {\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n UpdateWebhookRequest webhookRequest = new\n UpdateWebhookRequest.Builder().\n description(\"My updated webhook\").\n build();\n\n Response<Webhook> webhook = nylas.webhooks().update(\"<WEBHOOK_ID>\", \n webhookRequest);\n System.out.println(webhook.getData());\n }\n}\n"
- lang: kotlin
label: Kotlin SDK
source: "import com.nylas.NylasClient\nimport com.nylas.models.UpdateWebhookRequest\n\nfun main(args: Array<String>){\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val webhookRequest : UpdateWebhookRequest =\n UpdateWebhookRequest.Builder().\n description(\"My updated webhook\").\n build()\n\n val webhooks = nylas.webhooks().update(\"<WEBHOOK_ID>\", \n webhookRequest)\n println(webhooks.data)\n}\n"
delete:
operationId: delete-webhook-by-id
tags:
- Webhook Notifications
summary: Delete a webhook destination
description: Delete a webhook destination record.
security:
- NYLAS_API_KEY: []
parameters:
- name: id
in: path
schema:
type: string
required: true
responses:
'200':
$ref: '#/components/responses/delete_200'
description: Returns a success message.
'400':
$ref: '#/components/responses/delete_400'
description: Returns an error message.
x-code-samples:
- lang: bash
label: cURL
source: "curl --request DELETE \\\n --url 'https://api.us.nylas.com/v3/webhooks/<WEBHOOK_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
- lang: javascript
label: Node.js SDK
source: "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst deleteWebhook = async () => {\n try {\n await nylas.webhooks.destroy({ webhookId: \"<WEBHOOK_ID>\" });\n console.log(\"Webhook deleted successfully.\");\n } catch (error) {\n console.error(\"Error deleting webhook:\", error);\n }\n};\n\ndeleteWebhook();\n"
- lang: python
label: Python SDK
source: "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nrequest = nylas.webhooks.destroy(\n \"<WEBHOOK_ID>\",\n)\n\nprint(request)\n"
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nstatus = nylas.webhooks.destroy(webhook_id: \"<WEBHOOK_ID>\")\nputs status\n"
- lang: java
label: Java SDK
source: "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class webhooks {\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n WebhookDeleteResponse deleteResponse = \n nylas.webhooks().destroy(\"<WEBHOOK_ID>\");\n System.out.println(deleteResponse);\n }\n}\n"
- lang: kotlin
label: Kotllin SDK
source: "import com.nylas.NylasClient\n\nfun main(args: Array<String>){\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val webhooks = nylas.webhooks().destroy(\"<WEBHOOK_ID>\")\n println(webhooks.data)\n}\n"
/v3/webhooks/rotate-secret/{id}:
post:
operationId: post-new-secret
tags:
- Webhook Notifications
summary: Rotate a webhook secret
description: 'Update the webhook secret value for a destination. The previous value will immediately stop being used and the new value will take over.
### Webhook notification header
Every webhook notification Nylas sends includes the `x-nylas-signature` header. Depending on the SDK you''re using, you might see `X-Nylas-Signature` instead.'
x-code-samples:
- lang: bash
label: cURL
source: "curl --request POST \\\n --url 'https://api.us.nylas.com/v3/webhooks/rotate-secret/<WEBHOOK_ID>' \\ \n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'"
- lang: javascript
label: Node.js SDK
source: "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst rotated = await nylas.webhooks.rotateSecret({\n webhookId: \"<WEBHOOK_ID>\",\n});\n\nconsole.log(\"Rotated webhook secret:\", rotated);\n"
- lang: python
label: Python SDK
source: "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nwebhook = nylas.webhooks.rotate_secret(\n \"<WEBHOOK_ID>\"\n)\n\nprint(webhook)\n"
- lang: ruby
label: Ruby SDK
source: "# frozen_string_literal: true\n\n# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n api_key: '<NYLAS_API_KEY>'\n)\n\nsecret, _ = nylas.webhooks.rotate_secret(webhook_id: \"<WEBHOOK_ID>\")\n\nputs secret\n"
- lang: java
label: Java SDK
source: "import com.nylas.NylasClient;\nimport com.nylas.models.*;\nimport java.util.List;\n\npublic class read_grants {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n Response<WebhookWithSecret> secret = nylas.webhooks().rotateSecret(\"<WEBHOOK_ID>\");\n \n System.out.println(secret);\n }\n}\n"
- lang: kotlin
label: Kotlin SDK
source: "import com.nylas.NylasClient\nimport com.nylas.models.UpdateGrantRequest\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val secret = nylas.webhooks().rotateSecret(\"<WEBHOOK_ID>\")\n \n print(secret)\n}\n"
security:
- NYLAS_API_KEY: []
parameters:
- name: id
in: path
schema:
type: string
required: true
responses:
'200':
$ref: '#/components/responses/rotate_secret_200'
description: Returns the updated Destination.
'400':
$ref: '#/components/responses/delete_400'
/v3/webhooks/mock-payload:
post:
operationId: get_mock_webhook_payload
tags:
- Webhook Notifications
summary: Get mock notification payload
description: 'Use this endpoint to see example notification payloads for the different Nylas events you specify,
to the webhook URL you specify.'
x-code-samples:
- lang: bash
label: cURL
source: "curl --request POST \\\n --url 'https://api.us.nylas.com/v3/webhooks/mock-payload' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data '{\n \"trigger_type\": \"calendar.created\",\n \"webhook_url\": \"<WEBHOOK_URL>\"\n }'"
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/get_mock_payload_200'
description: Returns the mock payload for corresponding trigger type.
'400':
$ref: '#/components/responses/400'
requestBody:
required: true
description: Destination definition
content:
application/json:
schema:
$ref: '#/components/schemas/get_mock_payload_input'
/v3/webhooks/send-test-event:
post:
operationId: send_test_event
tags:
- Webhook Notifications
summary: Send test event
description: 'Use this endpoint to check if your project''s webhook destination is configured correctly. Nylas
sends a test webhook payload to the webhook URL you specify, and listens for a success
acknowledgement.
The secret used is `mock-webhook-secret`.'
x-code-samples:
- lang: bash
label: cURL
source: "curl --request POST \\\n --url 'https://api.us.nylas.com/v3/webhooks/send-test-event' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data '{\n \"trigger_type\": \"calendar.created\",\n \"webhook_url\": \"<WEBHOOK_URL>\"\n }'"
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/send_test_event_200'
description: Returns the mock payload for corresponding trigger type.
'400':
$ref: '#/components/responses/400'
requestBody:
required: true
description: Destination definition
content:
application/json:
schema:
$ref: '#/components/schemas/send_test_event_input'
components:
responses:
get_mock_payload_200:
description: Webhook Payload Returned
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
data:
type: object
description: This object is an example payload that Nylas sends to your webhook destination
request_id:
type: string
description: The ID for each request.
create_400:
description: Destination not created
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
type:
type: string
description: An alphanumeric code that represents the error type.
example: '70005'
message:
type: string
description: A human-readable message with details about the error.
example: 'unable.verify.webhook_url : status is not ok, got 404'
request_id:
type: string
description: The ID of the request.
delete_400:
description: Notification channel not deleted
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
type:
type: string
description: An alphanumeric code that represents the error type.
example: '70000'
message:
type: string
description: A human readable message with details about the error.
example: 'destination.id.not.found : record not found'
request_id:
type: string
description: The unique ID of the request that generated this response.
delete_200:
description: Destination Deleted
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
status:
type: string
enum:
- success
request_id:
type: string
description: The ID for each request.
get_400:
description: Destination not returned
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
type:
type: string
description: An alphanumeric code that represents the error type.
example: '70001'
message:
type: string
description: A human readable message with details about the error.
example: application_id.required
request_id:
type: string
description: The ID for each request.
get_by_id_200:
description: Destinations Returned
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: A unique identifier for the webhook destination.
example: UMWjAjMeWQ4D8gYF2moonK4486
description:
type: string
description: A human-readable description of the webhook destination.
example: Production webhook destination
trigger_types:
type: array
items:
type: string
enum:
- calendar.created
- calendar.updated
- calendar.deleted
- event.created
- event.updated
- event.deleted
- grant.created
- grant.updated
- grant.deleted
- grant.expired
- message.send_success
- message.send_failed
- message.bounce_detected
- message.created
- message.updated
- contact.updated
- contact.deleted
- folder.created
- folder.updated
- folder.deleted
- message.opened
- message.link_clicked
- thread.replied
description: 'The event that triggers the webhook notification. See the
[notification schemas](/docs/reference/notifications/) for details about
each trigger type.
See the [Grants](/docs/reference/api/manage-grants/),
[Calendar](/docs/reference/api/calendar/), [Events](/docs/reference/api/events/), and
[Messages](/docs/reference/api/messages/) references for information on how to trigger
each event type.'
webhook_url:
type: string
description: The URL to send webhooks to.
example: https://example.com/webhooks
status:
type: string
description: The status of the new destination.
enum:
- active
- pause
- failing
- failed
notification_email_addresses:
type: array
items:
type: string
description: 'The email addresses that Nylas notifies when a webhook is down for a while. See
[Failing and failed webhooks](/docs/v3/notifications/#failing-and-failed-webhooks) for
details.'
example:
- jane@example.com
- joe@example.com
status_updated_at:
type: integer
description: The time the `status` field was last updated, represented as a Unix timestamp in seconds.
example: 1234567890
created_at:
type: integer
description: The time the webhook destination was created, represented as a Unix timestamp in seconds.
example: 1234567890
updated_at:
type: integer
description: The time the webhook destination was last updated, represented as a Unix timestamp in seconds.
example: 1234567890
request_id:
type: string
description: The ID for each request.
'400':
description: Bad Request
content:
application/json:
schema:
title: error
type: object
properties:
request_id:
type: string
description: The request ID.
error:
type: object
description: The response error object.
properties:
type:
type: string
description: The error type.
message:
type: string
description: The error message.
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nylas/refs/heads/main/openapi/nylas-webhook-notifications-api-openapi.yml