Build for free
hero banner

How to set up Nylas API Webhooks using Hookdeck

• 6 min read
Jump to section
Author: Nylas
Nylas
Tags:
Jump to section

Updated Nov 2026

To test Nylas webhooks on your machine, run a local server behind a public HTTPS tunnel, register the tunnel URL as a webhook destination, return the challenge value, and verify the X-Nylas-Signature header on each notification. Nylas blocks requests to ngrok URLs, so use the Nylas CLI’s built in tunnel, VS Code port forwarding or Hookdeck.

In this guide you set up a Nylas v3 webhook destination, receive real notifications on localhost, and verify them. It uses the Nylas Node SDK for Hookdeck and Python for the local server.


In this blog post, we’ll dive into how to use and set up Nylas webhooks in API v3 using Hookdeck!

How does Nylas verify my webhook URL?

When you create a webhook, Nylas sends a GET request to your URL with a challenge query parameter. Your endpoint must answer 200 with the exact challenge value as the body. A failed challenge returns 400. Nylas then returns the webhook secret once, in the create response or in the Dashboard. Hookdeck answers the challenge for you.

How do I test webhooks locally?

ToolHow to use it
Nylas CLInylas webhook server starts a local server (port 4567 by default) and creates a tunnel. nylas webhook test send <WEBHOOK_URL> sends a test payload.
HookdeckCreate a connection with a CLI (localhost) destination.
VS Code port forwardingForward your local port from VS Code to get a public URL.

How do I verify a Nylas webhook signature in Python?

Nylas signs each notification with an HMAC-SHA256 of the raw request body, keyed with your 

webhook_secret, and sends it hex encoded in the X-Nylas-Signature header. Compare it with a constant time check. Nylas signs compressed notifications over the gzip bytes, so verify the signature first and decompress second. Then add the Flask sample in the next row.

How does Nylas retry failed webhooks?

Nylas tries up to 3 times in total when your endpoint returns 408, 429, 502, 503, 504, 507 or times out. For other error codes it drops the notification and keeps sending others. Delivery is at least once, so you may get duplicates. Message notifications over 1 MB arrive with a ‘.truncated’ type, and you fetch the full object by its ID.

How do I set up Nylas webhooks with Hookdeck?

We will first use Hookdeck to set up an endpoint for registering and receiving webhooks. So create a new connection in Hookdeck and call it testing-nylas-webhooks:

For the next section, define your event destination, let’s set up the destination as CLI (localhost) to test webhook locally:

We will keep the connection rules and name unchanged, and click Create:

Now we will be given the webhook URL to receive webhooks from Nylas:

In the upcoming sections, this URL is used as an environment variable, NYLAS_WEBHOOK_URL. Now that we have created the initial webhook URL.

How do I configure the webhook in Hookdeck?

So we have an active endpoint, and when Nylas receives a create webhook request from us, to ensure the endpoint is active we must respond with the query challenge. Hookdeck will handle authenticating or handshaking with Nylas webhook automatically, so we are not required to complete any additional steps here.

After successfully setting up the webhook, each subsequent call will not contain the query challenge, where Hookdeck will respond with a status 200 to notify Nylas that the webhook event was received successfully.

Now we have completed setting up Hookdeck and are ready to test creating a Nylas webhook.

How do I test the webhook?

Let’s look at how to create a Nylas webhook using the endpoint, NYLAS_WEBHOOK_URL, that we created on Hookdeck in the previous sections. 

Separately, we can also setup a webhook using the Nylas Dashboard:

To get started with using the Nylas v3 Node SDK, take a look at our getting started guide. For a more detailed guide, we also have a quickstart guide for creating webhooks.

Here is a code sample for creating a webhook:

import 'dotenv/config';
import Nylas, { WebhookTriggers } from "nylas"

const NylasConfig = {
  apiKey: process.env.NYLAS_API_KEY as string,
  apiUri: process.env.NYLAS_API_URI as string,
};

const nylas = new Nylas(NylasConfig);

const createWebhook = async () => {
  try {
    const webhook = await nylas.webhooks.create({
      requestBody: {
        triggerTypes: [WebhookTriggers.EventUpdated],
        callbackUrl: process.env.NYLAS_WEBHOOK_URL as string,
        description: "My first webhook",
        notificationEmailAddress: process.env.EMAIL as string,
      }
    });

    console.log("Webhook createdd:", webhook);
  } catch (error) {
    console.error("Error creating webhook:", error);
  }
}

createWebhook();

Now let’s run this code in the terminal:

node create-webhook.js
Webhook created: {
  requestId: 'requestId',
  data: {
    id: 'webhookId',
    description: 'My first webhook',
    triggerTypes: [ event.updated' ],
    webhookUrl: 'NYLAS_WEBHOOK_URL',
    webhookSecret: 'webhookSecret,
    status: 'active',
    notificationEmailAddresses: null,
    statusUpdatedAt: 1707334858,
    createdAt: 1707334858,
    updatedAt: 1707334858
  }
}

With Hookdeck setup automatically handle the query challenge sent by Nylas, we are able to successfully create a Nylas webhook. Note the the webhookSecret value is used for securing Nylas webhooks.

In this code sample, we requested a notification any time a new event (event.updated) is created for a user that has connected their account. Here is a full list of webhook triggers. The general approach we will take next is as follows:

  1. We need a user grant to test out creating an event. Take a look at our documentation on how to create a test grant using the Nylas Developer Dashboard.
  2. Once we update an event, we can observe the webhook being received on Hookdeck. 

As an example, I have created a grant for my Gmail account:

So to try this out we can update an event via Google calendar:

And this will generate a new webhook event in Hookdeck showing the updated title parameter:

In this section, we set up a Nylas Webhook to send notifications anytime a connected user’s calendar events are updated.

What should I build next?

In this blog post, we covered how to start with Nylas Webhooks in API v3 using Hookdeck.

You can sign up for Nylas for free and start building! Continue building with Nylas by exploring different quickstart guides or by visiting our developer documentation.

Why is my webhook not firing?

Check four things: the endpoint is reachable over public HTTPS, the challenge completed, the subscription has the right trigger types, and the destination is not in a failing or failed state.

How long until notifications start for a new account?

Up to two minutes after the grant is authenticated.

Can I use ngrok?

No, Nylas blocks ngrok URLs.

Related resources

What to do when there’s no email admin
Why emails sent via your app go to spam (but Outlook delivers them just fine)

This post is part of our “What to do when there’s no email admin” series…

• 4 min read
Read more
What to do when there’s no email admin
How to fix Microsoft’s “service abuse mode” error

This post is part of our “What to do when there’s no email admin” series…

• 3 min read
Read more
What to do when there’s no email admin
How to read Office 365 spam headers: A simple guide for non-admins

This post is part of our “What to do when there’s no email admin” series…

• 4 min read
Read more