A webhook endpoint is a public URL sitting on the internet, and anything on the internet can send it a POST. If your app acts on whatever lands there, an attacker who guesses the URL can forge events: fake an inbound email, trigger a workflow, or feed your system garbage. The fix is to confirm two things before you trust a request, that you own the endpoint and that Nylas actually sent the payload, and both are built into how webhooks work.

This post covers verifying webhooks from two angles: the HTTP mechanics your endpoint implements, and the nylas CLI for testing a signature without standing up a server. I work on the CLI, so the terminal commands below are the ones I reach for when I'm debugging a signature mismatch.

Two layers of webhook trust

There are two separate checks, and they happen at different times. The first is a one-time endpoint challenge: when you register or activate a webhook, Nylas sends your URL a request with a challenge value you echo back, proving you control the endpoint. The second runs on every notification afterward: each delivery carries a cryptographic signature you verify against a shared secret, proving the payload is genuine and wasn't tampered with.

You need both because they defend against different things. The challenge stops you from accidentally registering an endpoint you don't own and confirms the URL is live. The signature stops anyone else from posting forged events to that URL once it's known. Skip the signature check and your public endpoint will trust any POST that reaches it, which is the most common webhook security mistake.

Pass the endpoint challenge

The first time you set up a webhook or flip one to active, Nylas sends a GET request to your endpoint with a challenge query parameter. Your endpoint has to return the exact value of that challenge in the body of a 200 OK response, within 10 seconds, or the webhook won't verify. It's a quick handshake that proves the URL is yours and reachable.

// Express: echo the challenge back to verify the endpoint
app.get("/webhooks/nylas", (req, res) => {
  res.status(200).send(req.query.challenge);
});

The response body must be the challenge value and nothing else, so don't wrap it in JSON or add whitespace your framework might inject. Once your endpoint passes the challenge, the webhook becomes active and starts receiving notifications. This step only runs at setup and on reactivation, so it's a handler you write once and rarely think about again, but the webhook won't deliver anything until it succeeds.

One caveat catches people on hosted tooling: some low-code or no-code endpoints don't surface the challenge query parameter to your logic at all, so you can't echo it back and the handshake can't complete automatically. If you hit that, you'll need to reach out to support rather than fight the platform, since the verification is gated on returning that exact value.

Get your webhook secret

After your endpoint passes the challenge, Nylas generates a webhook_secret for it. This secret is the signing key behind every signature you'll verify, and it's the value both sides share: the service signs each notification with it, and your endpoint uses the same secret to recompute and compare. Treat it like any other credential, stored server-side and never exposed in client code.

The secret is tied to the specific webhook, so each webhook destination has its own. You read it when you create the webhook, and you keep it somewhere your verification code can reach at request time. Because it's the only thing standing between your endpoint and forged traffic, a leaked webhook_secret is a reason to rotate, which is a one-command operation covered below.

Verify the signature on every notification

Every webhook notification includes an X-Nylas-Signature header (lowercase x-nylas-signature in some stacks), and that header is a hex-encoded HMAC-SHA256 signature of the request body, computed with your webhook_secret as the key. To verify a notification, recompute the same HMAC over the body you received and check that it matches the header. A match means the payload is genuine and unmodified; a mismatch means you drop the request.

const crypto = require("crypto");

function isGenuine(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest();
  const received = Buffer.from(signature, "hex");
  // Guard the length first: timingSafeEqual throws on a size mismatch.
  return (
    received.length === expected.length &&
    crypto.timingSafeEqual(received, expected)
  );
}

Most Nylas SDKs ship a webhook-verification helper that wraps this HMAC for you, so in application code you typically call that helper rather than hand-rolling the crypto. Knowing the mechanism still matters, because when a helper rejects a request it's almost always one of the body-handling problems below, not the helper itself.

Two details make or break this. First, sign the exact raw body you received, before any JSON parsing or reserialization, because even a reordered key or changed whitespace produces a different HMAC and the check fails. Second, compare with a constant-time function like timingSafeEqual rather than ===, so the comparison itself doesn't leak timing information an attacker could exploit. Guard the buffer lengths first, since timingSafeEqual throws on a size mismatch, which a malformed or truncated signature would otherwise trigger. Get the raw body and the constant-time compare right and the rest is a one-line HMAC.

Handle the compressed-body gotcha

Here's the detail that costs people an afternoon: Nylas can send webhook payloads compressed, and the HMAC-SHA256 signature is computed over the compressed bytes. You have to verify the signature against the raw, still-compressed request body, and only decompress after the check passes. Decompress first and the bytes you hash no longer match what was signed, so verification fails even when the request is completely genuine.

This trips up frameworks that helpfully decompress or parse the body before your handler sees it. The fix is to capture the raw request body as bytes, run the signature check on those exact bytes, and do your JSON parsing or decompression as a separate step afterward. If your verification is failing on requests you're sure are real, the body being transformed before you hash it is the first thing to check, and the compressed-bytes ordering is the usual culprit.

Test a signature with the CLI

Debugging a signature mismatch against live traffic is painful, so the CLI lets you check the math in isolation. nylas webhook verify takes a payload, a secret, and a signature, and tells you whether they match, with no server or live webhook involved. It's how I confirm whether the problem is my secret, my body handling, or something else before touching the endpoint.

nylas webhook verify \
  --payload-file ./payload.json \
  --secret <WEBHOOK_SECRET> \
  --signature <X_NYLAS_SIGNATURE>

You can pass the body inline with --payload instead of --payload-file for a quick check. Feeding it a captured payload, the real secret, and the X-Nylas-Signature value from a delivery isolates the verification step: if the CLI says it matches but your endpoint rejects the same request, the difference is in how your server reads the body, which points straight at the raw-body or compression issue.

Rotate the secret when you need to

A signing secret is a credential, and credentials sometimes need replacing, after a suspected leak, an employee offboarding, or routine hygiene. Rotating regenerates the webhook_secret for a webhook, and from that point Nylas signs with the new value. nylas webhook rotate-secret does it by webhook ID:

nylas webhook rotate-secret <webhook-id>

Plan the cutover, since notifications signed with the old secret stop verifying the moment you rotate. Update your endpoint's stored secret to the new value as part of the same change, and for a zero-downtime rotation, accept either the old or new secret for a short window while the switch propagates. Treating rotation as a deliberate step rather than an emergency is what keeps it from dropping events.

Common reasons a signature won't verify

Most verification failures aren't attacks; they're the body being changed before you hash it. When a real notification won't validate, work through a short list. Your framework may have parsed and re-serialized the JSON before your handler ran, changing the bytes. You may be decompressing the body before checking the signature instead of after. You may be using a stale secret because the webhook was rotated and your stored value wasn't updated. Or you captured the body as a parsed object rather than the raw string or bytes.

Each of these produces the same symptom, a mismatch on a request you know is genuine, which is why the raw body is the first thing to confirm. This is exactly where nylas webhook verify earns its place: feed it the captured payload, the secret, and the signature, and if they match in the CLI but fail at your endpoint, the problem is in how your server reads the request, not the secret or the signature itself. That single test splits the search space in half.

Act on a verified notification

Once a notification passes the signature check, you can trust its contents and route on them. A webhook body is a structured event with a type, like message.created or event.updated, and a data object holding the resource that changed, so your handler switches on type to decide what to do. Verifying first means that dispatch only ever runs on genuine events, never on something an attacker posted.

Acknowledge quickly and process asynchronously. Your endpoint should return a 200 fast, because a slow response can trigger retries and duplicate deliveries, so the durable pattern is to verify the signature, enqueue the event, return 200, and do the real work in a background worker. That keeps the verification path tight and the heavy lifting off the request that has to answer in seconds, and it means a burst of notifications can't back up your endpoint into timing out and looking unreachable.

Things to keep in mind

A short list of practices keeps webhook verification airtight.

• Verify the signature on every notification. A public endpoint that skips the check trusts any POST that reaches it, which is the core webhook risk.
• Hash the exact raw body. Sign the bytes you received before parsing; reserialized JSON produces a different HMAC and fails the check.
• Verify before decompressing. The signature is over the compressed bytes, so check it first and decompress after.
• Compare in constant time. Use a function like timingSafeEqual, not ===, so the comparison doesn't leak timing data.
• Store the webhook_secret server-side. It's the key to your signatures; rotate it with nylas webhook rotate-secret if it's ever exposed.
• Return 200 fast, work later. Verify, enqueue, and acknowledge quickly; a slow endpoint triggers retries and duplicate deliveries.

Wrapping up

Two checks make a webhook endpoint trustworthy: echo the challenge once to prove you own the URL, then verify the X-Nylas-Signature HMAC-SHA256 on every delivery to prove each payload is genuine. The traps are all about the body, hash the exact raw bytes, verify before decompressing, and compare in constant time. When a signature won't validate, nylas webhook verify lets you check the math off to the side, and nylas webhook rotate-secret handles the secret when it needs to change.

Where to go next:

• Webhooks overview — the challenge handshake, the secret, and the signature header in full
• Receive webhooks with the CLI — forward and inspect notifications locally
• Nylas CLI webhook commands — nylas webhook verify and rotate-secret