Set up local webhook testing for the Nylas Node.js SDK
Nylas SDKs support local webhook testing. When you implement this feature, SDKs create a tunnel connection to a websocket server and register it as a webhook callback to your Nylas account.
What you'll learn
In this tutorial, you'll learn how to set up your local webhook testing for the Nylas Node.js SDK.
Step 1: Initialize the Nylas object
The Nylas
object provides access to every resource in Nylas APIs. Before making any request, you must initialize the Nylas
object with your client ID, client secret, and access token.
-
Call the
config
function and pass your client ID (<CLIENT_ID>
) and client secret (<CLIENT_SECRET>
). -
Call the
with
function and pass your access token (<ACCESS_TOKEN>
).
const Nylas = require('nylas');
Nylas.config({
clientId: <CLIENT_ID>,
clientSecret: <CLIENT_SECRET>
});
const nylas = Nylas.with(<ACCESS_TOKEN>);
Step 2: Change the base API URL
You can optionally change the base API URL depending on your location:
Location | API URL | Scheduler API URL |
---|---|---|
United States (Oregon) | https://api.nylas.com |
https://api.schedule.nylas.com |
Europe (Ireland) | https://ireland.api.nylas.com |
https://ireland.api.schedule.nylas.com |
For more information, see Data residency and Migration guide for data centers.
To change the base URL to the EU (Ireland) region, set apiServer: regionConfig[Region.Ireland].nylasAPIUrl
. The base API URL defaults to the US region.
const Nylas = require('nylas');
Nylas.config({
clientId: <CLIENT_ID>,
clientSecret: <CLIENT_SECRET>,
apiServer: regionConfig[Region.Ireland].nylasAPIUrl
});
const nylas = Nylas.with(<ACCESS_TOKEN>);
Step 3: Initialize the tunnel connection
Call openWebhookTunnel
to initialize the tunnel connection.
openWebhookTunnel: (config: OpenWebhookTunnelOptions) => Promise<Webhook>
Set callbacks and configuration parameters
The onMessage
callback is required, while other callbacks and configuration parameters are optional. The onMessage
callback returns a parsed delta event from the webhook server.
The following are supported callbacks and parameters:
export interface OpenWebhookTunnelOptions {
onMessage: (msg: WebhookDelta) => void; // Executes on receiving a notification
onConnectFail?: (error: Error) => void; // Executes when an error occurs during initial connection
onError?: (error: Error) => void; // Executes when an error is encountered during the server runtime
onClose?: (wsClient: WebSocketClient) => void; // Executes after the connection has closed
onConnect?: (wsClient: WebSocketClient) => void; // Executes 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.
}
Learn more about Webhook notification triggers.
Example
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: "CLIENT_ID",
clientSecret: "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 in to create, register, and open the webhook tunnel for testing
openWebhookTunnel({
onMessage: onMessageListener
}).then(r => console.log("Webhook connected and active. " + r))
More resources
- Learn about Webhooks.
- Learn about the Webhhooks API endpoint.
- Learn about CLI: Testing webhooks.