You want your app to react the moment a user gets an email or a meeting moves on their calendar. Polling the API every few minutes is wasteful, slow, and rate-limited. The native push systems are worse: Gmail wants a Cloud Pub/Sub topic, Microsoft Graph wants subscriptions you renew every few days, and IMAP gives you nothing but a long-lived connection you keep open and babysit.
Nylas webhooks replace all of that with one push channel. You subscribe a single HTTPS endpoint to the triggers you care about, and the API POSTs a JSON notification the instant a matching event fires on any connected account.
Why use Nylas webhooks instead of native provider push?
Section titled “Why use Nylas webhooks instead of native provider push?”Native push notifications work differently on every provider, so a multi-provider app ends up maintaining three separate systems. Nylas normalizes all of them into one webhook with one payload schema, so the same message.created handler fires whether the account is Gmail, Outlook, or a generic IMAP server. You build the integration once instead of three times.
The table contrasts the native setup for each provider with the single unified webhook.
| Approach | Setup | Renewal | Providers covered |
|---|---|---|---|
| Gmail API push | Create a Cloud Pub/Sub topic, grant publish rights | Re-watch the mailbox every 7 days | Google only |
| Microsoft Graph subscriptions | Register a subscription per resource | Renew before expiry (~3 days) | Microsoft only |
| IMAP | Hold a persistent connection open per mailbox | Reconnect on every drop | IMAP servers only |
| Nylas webhooks | One POST /v3/webhooks/ with a list of triggers | None (managed automatically) | All six providers |
How do webhooks work with the Nylas APIs?
Section titled “How do webhooks work with the Nylas APIs?”A webhook is a push subscription: you register an HTTPS URL and a list of trigger_types, and Nylas sends an HTTP POST with a JSON body each time one of those events occurs. There are 43 trigger types spanning messages, threads, calendars, events, contacts, folders, grants, bookings, and Notetaker. Your endpoint must return 200 OK within 10 seconds.
The notification carries the affected object so you can act without a follow-up request. A message.created payload, for example, includes the message metadata and IDs your handler needs to fetch the full message or update your database. The complete catalog of payloads lives in the webhook notification schemas.
How do I get notified of new email?
Section titled “How do I get notified of new email?”Subscribe a webhook to the message.created trigger. Nylas fires it whenever a new message lands in any connected mailbox, across all 6 providers, with no per-provider push configuration. Create the destination with a single request to POST /v3/webhooks/, passing your HTTPS endpoint as webhook_url and the triggers you want in trigger_types.
The request below subscribes one endpoint to new-message events. You can add more triggers to the same array. Subscribing to grant.expired alongside it tells you when an account needs re-authentication.
curl --request POST \ --url 'https://api.us.nylas.com/v3/webhooks/' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <NYLAS_API_KEY>' \ --data-raw '{ "trigger_types": ["message.created", "grant.expired"], "webhook_url": "https://yourapp.com/webhooks/nylas", "description": "New email notifications" }'For the full create flow with Node.js, Python, Ruby, Java, and Kotlin samples, see Using webhooks with Nylas.
How do I track email opens, clicks, and replies?
Section titled “How do I track email opens, clicks, and replies?”Three triggers report engagement on messages you send: message.opened fires when a tracking pixel loads, message.link_clicked fires when someone clicks a tracked link, and thread.replied fires when someone replies to a tracked thread. They require message tracking on the send request, so the open and click events only arrive for messages you sent with tracking turned on.
Subscribe to any combination of the 3 by adding them to trigger_types, and they report uniformly across all 6 providers you send through. Open and click tracking rely on a pixel and rewritten links, so they carry the usual caveats: a client that blocks images suppresses the open event. See message tracking for how to enable it and what each payload contains.
How do I sync calendar events in real time?
Section titled “How do I sync calendar events in real time?”Subscribe to the 3 event triggers event.created, event.updated, and event.deleted to mirror calendar changes as they happen. These fire for the calendar-capable providers (Google, Microsoft, iCloud, and Exchange) through the same webhook, so a meeting added in Outlook and one added in Google Calendar reach your endpoint with the same payload shape.
Add the calendar.created, calendar.updated, and calendar.deleted triggers if you also track calendars being added or removed. Yahoo and standard IMAP accounts connect over IMAP, which has no calendar, so the event triggers never fire for them. This is the unified answer to per-provider calendar push: instead of Google Calendar watch channels and Graph event subscriptions maintained on their own, one webhook covers both. The event.updated payload carries the full updated event object and its identifiers, so your handler can update its copy without re-listing the whole calendar.
How do I verify a webhook notification is genuine?
Section titled “How do I verify a webhook notification is genuine?”Nylas proves authenticity in two steps. First, when you create or activate a webhook, the API sends a GET request with a challenge query parameter that your endpoint must echo back in the body of a 200 OK response within 10 seconds. Returning the exact value, with no quotes or extra data, completes verification and generates your webhook_secret.
After that, every notification carries an X-Nylas-Signature header: a hex-encoded HMAC-SHA256 of the raw request body, signed with your webhook_secret. Recompute the HMAC over the unmodified body and compare before trusting the payload. The webhook security details cover signature checks, and webhook best practices covers retries, ordering, and compressed delivery.
What’s next
Section titled “What’s next”- Using webhooks with Nylas for the full setup, verification, and failure handling
- Webhook notification schemas for every trigger’s payload
- Create Webhook Destination for the API reference
- Webhook best practices for retries, duplicate handling, and scaling