Only show these results:

Test webhooks locally with the Nylas Node.js SDK

🚀 Local webhook testing for the v3 Node.js SDK is coming soon.

Nylas SDKs support local webhook testing. When you implement this feature, the SDKs create a tunnel connection to a websocket server and register it as a webhook callback to your Nylas account.

What you'll learn

This page discusses how to set up local webhook testing for the Nylas Node.js SDK.

Step 1: Initialize the Nylas object

For v3, the Nylas object provides access to every resource in the Nylas API. Before you make any API requests, you must initialize the Nylas object with your API_KEY and API_URI.

import Nylas from "nylas"

const NylasConfig = {
apiKey: '<API_KEY>',
apiUri: '<API_URI>',
};

const nylas = new Nylas(NylasConfig)
const applicationDetails = await nylas.applications.getDetails()

For v2, the Nylas object provides access to every resource in the Nylas API. Before you make any API requests, you must initialize the Nylas object with your client ID, client secret, and access token:

  1. Call the .config() function and pass your <NYLAS_CLIENT_ID> and <NYLAS_CLIENT_SECRET>.
  2. Call the .with() function and pass your <ACCESS_TOKEN>.

All together, your code should look like the example below.

const Nylas = require('nylas');

Nylas.config({
clientId: <NYLAS_CLIENT_ID>,
clientSecret: <NYLAS_CLIENT_SECRET>
});

const nylas = Nylas.with(<ACCESS_TOKEN>);

Step 2: (Optional) Change the base API URL

You can choose to change the base API URL depending on your location, as in the table below.

Location Nylas and Scheduler API URL (v3) Nylas API URL (v2) Scheduler API URL (v2)
United States (Oregon) https://api.us.nylas.com https://api.nylas.com https://api.schedule.nylas.com
Europe (Ireland) http://api.eu.nylas.com https://ireland.api.nylas.com https://ireland.api.schedule.nylas.com

For more information, see the data residency documentation and the Migration guide for data centers.

To change the API URL in Nylas v3, pass the API_URI parameter to new Nylas(NylasConfig).

import Nylas from "nylas"

const NylasConfig = {
apiKey: '<API_KEY>',
apiUri: '<API_URI>',
};

const nylas = new Nylas(NylasConfig)
const applicationDetails = await nylas.applications.getDetails()

To change the API URL in v2, pass the API_URL parameter to Nylas.config().

const Nylas = require('nylas');

Nylas.config({
clientId: <NYLAS_CLIENT_ID>,
clientSecret: <NYLAS_CLIENT_SECRET>,
apiServer: regionConfig[Region.Ireland].nylasAPIUrl
});

const nylas = Nylas.with(<ACCESS_TOKEN>);

🔍 The base API URL defaults to the Nylas U.S. region. If you're using the E.U. region in Nylas v2, you can specify apiServer: regionConfig[Region.Ireland].nylasAPIUrl. See the data residency documentation for more information.

Step 3: Initialize the tunnel connection

Use the following code to call openWebhookTunnel and initialize the tunnel connection.

openWebhookTunnel: (config: OpenWebhookTunnelOptions) => Promise<Webhook>   

Step 4: Set callbacks and configuration parameters

You can set methods to override the websocket client's callback methods and set its configuration parameters. You must set the onMessage callback method to parse delta events from the webhook server. The other callbacks and configuration parameters are optional.

Nylas supports the following callbacks and configuration parameters:

export interface OpenWebhookTunnelOptions {
onMessage: (msg: WebhookDelta) => void; // Runs on receiving a notification.
onConnectFail?: (error: Error) => void; // Runs when an error occurs during initial connection.
onError?: (error: Error) => void; // Runs when an error is encountered during the server runtime.
onClose?: (wsClient: WebSocketClient) => void; // Runs after the connection has closed.
onConnect?: (wsClient: WebSocketClient) => void; // Runs when the initial server connection is established.
region?: Region; // The region to connect to. Supported regions are 'us' (US) and 'ireland' (EU). Defaults to 'us'.
triggers?: WebhookTriggers[]; // The list of webhook triggers to listen on. Defaults to all.
}

Example: Set up local webhook testing

The following example sets up local webhook testing for the Nylas Node.js SDK.

const Nylas = require('nylas');
const { openWebhookTunnel } = require('nylas/lib/services/tunnel');

// Initialize an instance of the Nylas SDK using the client credentials.
Nylas.config({
clientId: "NYLAS_CLIENT_ID",
clientSecret: "NYLAS_CLIENT_SECRET",
});

const nylas = Nylas.with(<ACCESS_TOKEN>);

// Define the callback for the onMessage event.
const onMessageListener = (delta) => {
if(delta.type === WebhookTriggers.MessageUpdated) {
console.log("Got message from webhook. Data: " + delta.objectData);
}
}

// Pass your config to create, register, and open the webhook tunnel for testing.
openWebhookTunnel({
onMessage: onMessageListener
}).then(r => console.log("Webhook connected and active. " + r))

More resources