Only show these results:

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

Step 1: Initialize the Nylas object

from nylas import APIClient

nylas = APIClient(

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)
Europe (Ireland)

For more information, see Data residency and Migration guide for data centers.

from nylas import APIClient

nylas = APIClient(

Step 3: Initialize the tunnel connection

Call open_webhook_tunnel to initialize the tunnel connection.

def open_webhook_tunnel(api, config)   

Set callbacks and configuration parameters

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 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 => dict (representing a Nylas delta)
def on_open(ws): # ws => WebSocketClient object
def on_close(ws): # ws => WebSocketClient object
def on_error(ws, err): # ws => WebSocketClient object, err => Error object


from nylas import APIClient
from import open_webhook_tunnel
from nylas.client.restful_models import Webhook

# Initialize an instance of the Nylas SDK using the client credentials
nylas = APIClient(

# Define the callbacks (optional)
def run_webhook():
def on_message(delta):
if delta["type"] == Webhook.Trigger.MESSAGE_UPDATED:

def on_open(ws):

def on_error(ws, err):
print("Error found")

# Pass your config in to create, register, and open the webhook tunnel for testing
nylas, {"on_message": on_message, "on_open": on_open, "on_error": on_error}


More resources