Version:
Only show these results:

Test webhooks locally with the Nylas Ruby SDK

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

The SDKs for Nylas v2 support local webhook testing. When you test your webhooks locally, the SDK creates a tunnel connection to a websocket server and registers it to your Nylas account as a webhook callback.

What you'll learn

In this tutorial, you'll learn how to set up your local webhook testing for the Nylas Ruby SDK.

Initialize the Nylas object

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>);

(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 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 the Nylas data residency documentation and the Migration guide for data centers.

To change the base API URL, set api_server to the API URL of your location.

🔍 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 api_server: 'https://ireland.api.nylas.com'.

#!/usr/bin/env ruby

NYLAS_CLIENT_ID = '<NYLAS_CLIENT_ID>'
NYLAS_CLIENT_SECRET = '<NYLAS_CLIENT_SECRET>'
ACCESS_TOKEN = '<NYLAS_ACCESS_TOKEN>'
API_URL= '<NYLAS_API_URL>'

require 'nylas'

nylas = Nylas::API.new(
    app_id: NYLAS_CLIENT_ID,
    app_secret: NYLAS_CLIENT_SECRET,
    access_token: ACCESS_TOKEN,
    api_server: API_URL
)

Initialize the tunnel connection

Call .open_webhook_tunnel() to initialize the tunnel connection:

def self.open_webhook_tunnel(api, config = {})

Set callbacks and configuration parameters

You can pass methods to override the websocket client's callback methods using config.

Although all callbacks and configuration parameters are optional, we recommend setting the on_message callback to process notifications as they come in. The on_message callback returns a parsed delta event from the webhook server.

This code snippet defines the on_message callback with the region and the webhook trigger:

config = {
  "region": "us",
  "triggers": [WebhookTrigger::MESSAGE_UPDATED],
  "on_message": method(:on_message)
}

Nylas supports the following callbacks and configuration parameters:

config = {
  "on_message" func, # Runs on receiving a notification.
  "on_open" func, # Runs when the initial server connection has been established.
  "on_error" func, # Runs when an error is encountered during the server runtime.
  "on_close" func, # Runs after the connection has closed.
  "region": string,  # The region to connect to. Supported regions are 'us' (US) and 'ireland' (EU). Defaults to US.
  "triggers": list[Webhook.Trigger], # The list of webhook triggers to listen on. Defaults to all.
}

Learn more about Webhook notification triggers.

We recommend that you follow these function signatures to avoid errors:

def on_message(delta): # delta => Nylas::Delta object
def on_open(event): # event => Websocket event
def on_close(event): # ws => Websocket event
def on_error(err): # err => Error object

Example: Set up local webhook testing

#!/usr/bin/env ruby

NYLAS_CLIENT_ID = '<NYLAS_CLIENT_ID>'
NYLAS_CLIENT_SECRET = '<NYLAS_CLIENT_SECRET>'
ACCESS_TOKEN = '<ACCESS_TOKEN>'
require 'nylas'

# Initialize an instance of the Nylas SDK using the client credentials
nylas = Nylas::API.new(
    app_id: NYLAS_CLIENT_ID,
    app_secret: NYLAS_CLIENT_SECRET,
    access_token: ACCESS_TOKEN
)

# Define the callback for the on_message event (optional)
def on_message(delta)
  if delta.type == Nylas::WebhookTrigger::MESSAGE_UPDATED
    p [:delta, delta]
  end
end

# Config that sets the region, triggers, and callbacks (optional)
config = {
  "region": "us",
  "triggers": [WebhookTrigger::MESSAGE_UPDATED],
  "on_message": method(:on_message)
}

# Create, register, and open the webhook tunnel for testing
Nylas::Tunnel::open_webhook_tunnel(nylas, config)

Tutorials

Prefer video? You can watch our LiveStream Coding with Nylas.

How to test webhooks locally using Ruby

More resources