Version:
Only show these results:

Test webhooks locally with the Nylas Python SDK

🚀 Local webhook testing for the v3 Python SDK is coming soon.

The SDKs for Nylas v2 support local webhook testing. When you test your webhooks locally, the SDK creates a tunnel connection to a websocket server and registers it to your Nylas account as a webhook callback.

What you'll learn

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

Initialize the Nylas object

from nylas import APIClient

nylas = APIClient(
    NYLAS_CLIENT_ID,
    NYLAS_CLIENT_SECRET
)

Change the base API URL

You can choose to change the base API URL depending on your location, as in the table below.

Location Nylas 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 the Nylas data residency documentation and the Migration guide for data centers.

To change the base API URL, pass the API_URL parameter with the API URL of your location.

🔍 The base API URL defaults to the Nylas U.S. region. If you're using the E.U. region in Nylas v2, you can specify api_server='https://ireland.api.nylas.com'.

from nylas import APIClient

nylas = APIClient(
    NYLAS_CLIENT_ID,
    NYLAS_CLIENT_SECRET,
    ACCESS_TOKEN,
    API_URL
)

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

Example

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

# Initialize an instance of the Nylas SDK using the client credentials
nylas = APIClient(
    NYLAS_CLIENT_ID,
    NYLAS_CLIENT_SECRET
)

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

    def on_open(ws):
        print("opened")

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

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

More resources