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:
- Call the
.config()
function and pass your<CLIENT_ID>
and<CLIENT_SECRET>
. - 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
- Learn more about Webhooks.
- Learn more about the Webhhooks API endpoint.
- Learn about testing webhooks using the CLI.