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)
Video walkthroughs
Prefer video? You can watch our LiveStream Coding with Nylas.
How to locally test Webhooks using Ruby
More resources
- Learn about Webhooks.
- Learn about the Webhhooks API endpoint.
- Learn about CLI: Testing webhooks.