nylas-webhooks

Nylas Webhooks

When to Use This Skill

• How do I receive Nylas webhooks?
• How do I verify Nylas webhook signatures (x-nylas-signature)?
• How do I respond to the Nylas challenge handshake when creating a webhook?
• How do I handle message.created, message.opened, event.created, or grant.expired events?
• Why is my Nylas webhook signature verification failing (gzip / raw body)?

Verification (core)

Nylas signs the raw request body with HMAC-SHA256 keyed on your per-destination webhook_secret and sends the digest as a hex string in the x-nylas-signature header (casing varies — read it case-insensitively). This is not Standard Webhooks: there is no webhook-id/webhook-timestamp; only the body is signed. Verify the raw bytes before JSON parsing, and if Content-Encoding: gzip, verify against the compressed bytes and decompress only after the check passes. Nylas SDKs expose webhook CRUD, rotateSecret, and ipAddresses, but no signature-verify helper — implement the HMAC check yourself with a constant-time comparison.

Node:

const crypto = require('crypto');

function verifyNylasSignature(rawBody, signatureHeader, secret) {
  if (!signatureHeader || !secret) return false;
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signatureHeader, 'hex'),
      Buffer.from(expected, 'hex')
    );
  } catch {
    return false; // length mismatch = invalid
  }
}

Python:

import hmac, hashlib

def verify_nylas_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    if not signature_header or not secret:
        return False
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature_header, expected)

Challenge handshake (endpoint verification)

When a webhook destination is created (Dashboard or POST /v3/webhooks), Nylas sends a GET with a challenge query parameter. Echo the exact value back — plain text, nothing else — with 200 within 10 seconds (no chunked encoding). The webhook_secret is returned only on creation/rotation, so store it then.