Only show these results:

Set up local webhook testing for the Nylas Ruby SDK

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

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

Step 1: 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 <CLIENT_ID> and <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: <CLIENT_ID>,
 clientSecret: <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:

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.

Pass the API_URL parameter to change the base API URL:

#!/usr/bin/env ruby
CLIENT_ID = 'your_nylas_client_id'
CLIENT_SECRET = 'your_nylas_client_secret'
ACCESS_TOKEN = 'your_account_access_token'
API_URL='your_base_api_url'
require 'nylas'

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

If you're using the Nylas EU region: The base API URL defaults to the US region, but you can specify api_server: 'https://ireland.api.nylas.com' to use the EU region. See Data Residency for more information.

Step 3: Initialize the tunnel connection

Call .open_webhook_tunnel() to initialize the tunnel connection:

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

Step 4: 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

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
CLIENT_ID = 'your_nylas_client_id'
CLIENT_SECRET = 'your_nylas_client_secret'
ACCESS_TOKEN = 'your_account_access_token'
require 'nylas'

# Initialize an instance of the Nylas SDK using the client credentials
nylas = Nylas::API.new(
    app_id: CLIENT_ID,
    app_secret: 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