𝗛𝗮𝗻𝗱𝗹𝗲 𝗡𝘆𝗹𝗮𝘀 𝗪𝗲𝗯𝗵𝗼𝗼𝗸𝘀 𝗶𝗻 𝗡𝗲𝘅𝘁.𝗷𝘀

𝗛𝗮𝗻𝗱𝗹𝗲 𝗡𝘆𝗹𝗮𝘀 𝗪𝗲𝗯𝗵𝗼𝗼𝗸𝘀 𝗶𝗻 𝗡𝗲𝘅𝘁.𝗷𝘀

An email hits your AI agent. You have 10 seconds to respond.

If you use Nylas Agent Accounts, a message.created webhook hits your server immediately. In Next.js, you handle this with one route file.

Here is how to build it correctly.

𝗧𝗵𝗲 𝗖𝗵𝗮𝗹𝗹𝗲𝗻𝗴𝗲 𝗛𝗮𝗻𝗱𝘀𝗵𝗮𝗸𝗲

When you create a webhook, Nylas sends a GET request with a challenge parameter. You must return the exact value in the response body.

Do not use JSON. Do not add quotes. Use a bare response. If you fail this, the webhook fails.

Example GET handler:

export async function GET(req: NextRequest) { const challenge = req.nextUrl.searchParams.get("challenge"); return new Response(challenge ?? "", { status: 200 }); }

𝗧𝗵𝗲 𝗣𝗢𝗦𝗧 𝗡𝗼𝘁𝗶𝗳𝗶𝗰𝗮𝘁𝗶𝗼𝗻

When a message arrives, Nylas sends a POST request. Follow these three rules to avoid errors:

• Acknowledge immediately. Return a 200 status before you run your heavy logic. If your LLM takes too long, the webhook will time out.
• Verify signatures. Use the X-Nylas-Signature header and your webhook secret. This prevents unauthorized users from triggering your agent.
• Use the raw body. To verify the HMAC signature, you need the raw text. Read the text first, verify it, then parse the JSON.

Example POST handler:

export async function POST(req: NextRequest) { const raw = await req.text(); const signature = req.headers.get("x-nylas-signature") ?? "";

const expected = crypto .createHmac("sha256", process.env.NYLAS_WEBHOOK_SECRET!) .update(raw, "utf8") .digest("hex");

const valid = signature.length === expected.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

if (!valid) { return new Response("invalid signature", { status: 401 }); }

const payload = JSON.parse(raw); const { object } = payload.data;

processMessage(object.grant_id, object.id).catch(console.error);

return NextResponse.json({ ok: true }, { status: 200 }); }

𝗣𝗿𝗼𝗱𝘂𝗰𝘁𝗶𝗼𝗻 𝗧𝗶𝗽𝘀

• Deduplicate messages. Webhooks deliver at-least-once. Use a database constraint or Redis to ensure you do not process the same message twice. • Handle truncated payloads. If a message is over 1 MB, the body is stripped. Always re-fetch the message via the API to get the full content. • Use cleaned content. Use message.created.cleaned to get markdown instead of messy HTML. This works better for your LLM.

How do you handle deduplication in your webhook handlers? Do you use Redis or a database constraint?

Source: https://dev.to/qasim157/handle-messagecreated-webhooks-in-nextjs-4e80