Set up local webhook testing for the Ruby 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 Ruby 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.

Pass API_URL 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
)

Step 3: 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.

Use config to set callbacks and configuration parameters. Although all callbacks and configuration parameters are optional, Nylas recommends 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.

The following defines the on_message callback with the region and the webhook trigger:

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

The following are supported callbacks and parameters:

config = {
  "on_message" func, # Executes on receiving a notification
  "on_open" func, # Executes when the initial server connection has been established
  "on_error" func, # Executes when an error is encountered during the server runtime
  "on_close" func, # Executes 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.

The following are function signatures that you should follow 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

#!/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)