Receive webhooks with the CLI

The Nylas CLI includes built-in tools for receiving and testing webhook notifications locally, so you can develop webhook handlers without deploying to a public server.

Before you begin

Install the Nylas CLI and authenticate with your API key:

curl -fsSL https://cli.nylas.com/install.sh | bash
nylas init

If you haven’t set up the CLI yet, see Get started with the Nylas CLI for detailed instructions.

Start a local webhook server

The nylas webhook server command starts a local HTTP server and automatically creates a tunnel so Nylas can reach your machine. No additional tunneling tools are needed.

nylas webhook server

This starts a server on port 4567 by default. Use --port to change it:

nylas webhook server --port 8080

The CLI outputs a public tunnel URL that you can use as your webhook endpoint. Webhook events stream to your terminal in real time.

Nylas blocks requests to ngrok URLs. The built-in tunnel in nylas webhook server is the recommended alternative. You can also use VS Code port forwarding or Hookdeck.

Register a webhook

Once your local server is running, create a webhook subscription pointing to the tunnel URL:

nylas webhook create --url <TUNNEL_URL> --triggers message.created,grant.expired

Use nylas webhook triggers to see all available trigger types:

nylas webhook triggers

Send a test event

The CLI can send a test payload to any URL to verify your endpoint is working:

nylas webhook test send <WEBHOOK_URL>

You can also use the Nylas API’s Send Test Event and Get Mock Payload endpoints for more targeted testing.

Manage webhooks

List, update, and delete webhooks from the CLI:

nylas webhook list
nylas webhook update <WEBHOOK_ID>
nylas webhook delete <WEBHOOK_ID>

Verify webhook signatures

When your endpoint receives a notification, verify the x-nylas-signature header to confirm it’s genuine. The header contains a hex-encoded HMAC-SHA256 signature of the request body, signed with your webhook_secret.

For details on signature verification and the challenge handshake, see Secure a webhook.

What’s next

• Notification schemas — payload reference for all webhook triggers
• Using webhooks with Nylas — webhook setup, verification, and retry behavior
• Webhook best practices — production recommendations
• Nylas CLI command reference — full CLI documentation