𝗛𝗮𝗻𝗱𝗹𝗲 𝗡𝘆𝗹𝗮𝘀 𝗪𝗲𝗯𝗵𝗼𝗼𝗸𝘀 𝗶𝗻 𝗡𝗲𝘅𝘁.𝗷𝘀
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 }); }
𝗣𝗿𝗼𝗱𝘂𝗰𝘁𝗶𝗼𝗻 𝗧𝗶𝗽𝘀
• Loại bỏ tin nhắn trùng lặp. Webhook được gửi theo cơ chế "at-least-once". Sử dụng ràng buộc cơ sở dữ liệu hoặc Redis để đảm bảo bạn không xử lý cùng một tin nhắn hai lần.
• Xử lý các payload bị cắt bớt. Nếu một tin nhắn vượt quá 1 MB, phần thân sẽ bị lược bỏ. Luôn luôn lấy lại tin nhắn thông qua API để có được nội dung đầy đủ.
• Sử dụng nội dung đã được làm sạch. Sử dụng message.created.cleaned để lấy markdown thay vì HTML lộn xộn. Điều này sẽ hoạt động tốt hơn cho LLM của bạn.
Bạn xử lý việc loại bỏ trùng lặp trong các webhook handler của mình như thế nào? Bạn sử dụng Redis hay ràng buộc cơ sở dữ liệu?
Nguồn: https://dev.to/qasim157/handle-messagecreated-webhooks-in-nextjs-4e80