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

טיפול ב-Nylas Webhooks ב-Next.js

אימייל מגיע לסוכן ה-AI שלך. יש לך 10 שניות להגיב.

אם אתה משתמש ב-Nylas Agent Accounts, webhook מסוג message.created מגיע לשרת שלך באופן מיידי. ב-Next.js, מטפלים בזה באמצעות קובץ route אחד.

הנה איך לבנות זאת בצורה נכונה.

תהליך ה-Challenge Handshake

כשאתה יוצר webhook, Nylas שולחת בקשת GET עם פרמטר challenge. עליך להחזיר את הערך המדויק בגוף התגובה (response body).

אל תשתמש ב-JSON. אל תוסיף גרשיים. השתמש בתגובה פשוטה (bare response). אם תיכשל בזה, ה-webhook ייכשל.

דוגמה ל-GET handler:

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

הודעת ה-POST

כשמגיעה הודעה, Nylas שולחת בקשת POST. פעל לפי שלושת הכללים הבאים כדי למנוע שגיאות:

• אשר את הקבלה באופן מיידי. החזר סטטוס 200 לפני שאתה מריץ את הלוגיקה הכבדה שלך. אם ה-LLM שלך לוקח יותר מדי זמן, ה-webhook יחווה timeout.
• וודא חתימות (Verify signatures). השתמש בכותרת X-Nylas-Signature וב-webhook secret שלך. זה מונע ממשתמשים לא מורשים להפעיל את הסוכן שלך.
• השתמש ב-raw body. כדי לוודא את חתימת ה-HMAC, אתה זקוק לטקסט הגולמי (raw text). קרא את הטקסט תחילה, וודא אותו, ורק אז בצע parse ל-JSON.

דוגמה ל-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 });
}

טיפים לייצור (Production Tips)

• מניעת כפילויות הודעות. Webhooks מספקים הודעות בשיטת "לפחות פעם אחת" (at-least-once). השתמשו באילוץ מסד נתונים (database constraint) או ב-Redis כדי להבטיח שלא תעבדו את אותה הודעה פעמיים. • טיפול ב-payloads מקוטעים. אם הודעה גדולה מ-1 MB, גוף ההודעה נחתך. תמיד משכו מחדש את ההודעה באמצעות ה-API כדי לקבל את התוכן המלא. • שימוש בתוכן נקי. השתמשו ב-message.created.cleaned כדי לקבל markdown במקום HTML מבולגן. זה עובד טוב יותר עבור ה-LLM שלכם.

איך אתם מטפלים במניעת כפילויות ב-webhook handlers שלכם? האם אתם משתמשים ב-Redis או באילוץ מסד נתונים?

מקור: https://dev.to/qasim157/handle-messagecreated-webhooks-in-nextjs-4e80