Polling an AI agent's inbox wastes API calls and adds latency. A webhook-driven pipeline that fans inbound mail to a queue and processes it with workers is far more efficient for production use. This guide walks through the end-to-end architecture using Nylas, covering provisioning, webhook subscription, signature verification, and queue-based processing.
The case against polling
Most tutorials show a while True loop that polls an inbox every 30 seconds, runs new messages through a model, and sends a reply. That works for a demo, but in production the cracks show: you burn API calls fetching nothing 99% of the time, reaction latency is bounded by your poll interval, and scaling to multiple inboxes multiplies the cost. The mailbox already knows the instant a message arrives — there's no reason to keep asking.
A webhook-based pipeline solves this. Inbound mail fans out to a verified ingest endpoint, lands on a queue, and gets picked up by workers that drive the agent runtime and send the reply. The key components are idempotency, retries, ordering, and backpressure — the parts that bite you in production.
The Agent Account abstraction
Before the pipeline matters, you need the right mental model. An Agent Account is a Nylas grant — it has a grant_id, an inbox, an email address on a domain you own, and speaks every grant-scoped endpoint: Messages, Threads, Folders, Drafts, Attachments, Calendars, Events, Contacts, Webhooks. There's no OAuth token to refresh or provider-specific quirks. If you've built against a connected Gmail or Microsoft grant before, the data plane is identical.
What's different is that the agent is a participant with its own address — support@yourcompany.com — rather than borrowing a human's inbox. That makes the event-driven design clean: one grant, one inbox, one webhook stream, no shared-mailbox coordination problem. Provision one with a POST to /v3/connect/custom or the Nylas CLI, which auto-provisions a default workspace and policy. The email must be on a domain registered with Nylas; new domains warm over roughly four weeks before you push real volume.
The architecture, component by component
The flow is straightforward. Inbound mail triggers a message.created event, which hits an ingest endpoint that verifies the X-Nylas-Signature (HMAC-SHA256) and returns 200 immediately. The endpoint enqueues a small job with notification_id, grant_id, message_id, and thread_id. A worker picks up the job, fetches the full message via API (re-fetching if truncated), acquires a per-thread lock, runs the agent runtime to generate a reply, and sends it via POST to /messages/send. Deliverability events — delivered, bounced, complaint, rejected — route separately.
The guiding principle: the ingest endpoint does as little as possible. It verifies the signature, drops a small job on the queue, and returns 200. Everything expensive happens in a worker behind the queue. This keeps Nylas from retrying you — if your endpoint is slow to ack, Nylas assumes delivery failed and sends the event again.
One important detail: webhooks in Nylas are application-scoped, not grant-scoped. You subscribe once at the app level, and events for every grant in the application arrive at that single endpoint. Each payload carries a grant_id, and routing to the right agent is your handler's job. If you run several agents (support@, sales@, scheduling@), they share one webhook stream and you fan out on grant_id downstream.
Step 1: Subscribe to the webhook
You want message.created for inbound, and the four deliverability triggers for outbound visibility — message.delivered, message.bounced, message.complaint, and message.rejected. Agent Accounts emit all four; connected grants don't. Subscribe with a POST to /v3/webhooks or the CLI:
```bash
nylas webhook create \
--url https://pipeline.yourcompany.com/webhooks/nylas \
--triggers message.created,message.delivered,message.bounced,message.complaint,message.rejected \
--description "Support agent inbound + deliverability"
```
Both return a webhook record with a webhook_secret. Save it somewhere your ingest endpoint can read it — that secret is the signing key for the next step.
Step 2: Verify the signature, then ack fast
Every webhook Nylas sends includes an X-Nylas-Signature header — a hex-encoded HMAC-SHA256 of the raw request body, signed with your webhook_secret. Without verification, anyone who learns your webhook URL can POST fake message.created events and make your agent reply to mail that never arrived.
The thing that trips people up: verify against the exact bytes of the body. If your framework parses the JSON and re-serializes it before you hash, the bytes change and the signature won't match. Read the raw body first, verify, then parse. Use a timing-safe comparison to avoid timing attacks.
```javascript
import crypto from "node:crypto";
const WEBHOOK_SECRET = process.env.NYLAS_WEBHOOK_SECRET;
function isValidSignature(rawBody, signature) {
const expected = crypto
.createHmac("sha256", WEBHOOK_SECRET)
.update(rawBody) // exact bytes, not re-serialized JSON
.digest("hex");
const a = Buffer.from(expected, "utf8");
const b = Buffer.from(signature ?? "", "utf8");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
```
Ack first with a 200 status, then enqueue the job. Do real work behind the queue.
Step 3: Build the queue and worker
Your queue must support at-least-once delivery and deduplication on notification id. When a worker picks up a job, it fetches the full message from the Nylas API. If the message is truncated, re-fetch with expand=body. Acquire a per-thread lock to prevent concurrent replies to the same thread. Then run your agent runtime — call your model, generate the reply, and send it via POST to /messages/send.
For development, the Nylas CLI ships a local receiver: nylas webhook server --tunnel cloudflared --secret <your-webhook-secret> stands up an HTTP server, opens a Cloudflare tunnel, and verifies the signature on each event as it arrives. It's not your production ingest endpoint, but it's the fastest way to see the actual payload shape before you write a line of handler code.