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

التعامل مع Nylas Webhooks في Next.js

تصل رسالة بريد إلكتروني إلى وكيل الذكاء الاصطناعي الخاص بك. لديك 10 ثوانٍ فقط للرد.

إذا كنت تستخدم Nylas Agent Accounts، فسيصل webhook من نوع message.created إلى خادمك فوراً. في Next.js، يمكنك التعامل مع ذلك باستخدام ملف مسار (route file) واحد.

إليك كيفية بنائه بشكل صحيح.

مصافحة التحدي (The Challenge Handshake)

عند إنشاء webhook، ترسل Nylas طلب GET مع معامل challenge. يجب عليك إرجاع القيمة نفسها تماماً في جسم الاستجابة (response body).

لا تستخدم JSON. لا تضف علامات اقتباس. استخدم استجابة مجردة (bare response). إذا فشلت في ذلك، سيفشل الـ webhook.

مثال لمعالج GET:

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).
• تحقق من التوقيعات. استخدم رأس X-Nylas-Signature وسر الـ webhook الخاص بك. هذا يمنع المستخدمين غير المصرح لهم من تشغيل وكيلك.
• استخدم الجسم الخام (raw body). للتحقق من توقيع HMAC، ستحتاج إلى النص الخام. اقرأ النص أولاً، ثم تحقّق منه، وبعد ذلك قم بتحليل (parse) الـ JSON.

مثال لمعالج POST:

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 بالتسليم مرة واحدة على الأقل. استخدم قيداً في قاعدة البيانات (database constraint) أو Redis لضمان عدم معالجة الرسالة نفسها مرتين. • التعامل مع الحمولة المبتورة (truncated payloads). إذا تجاوزت الرسالة 1 ميجابايت، يتم اقتطاع محتواها. قم دائماً بإعادة جلب الرسالة عبر الـ API للحصول على المحتوى الكامل. • استخدام المحتوى المنقح. استخدم message.created.cleaned للحصول على markdown بدلاً من HTML غير المنظم. هذا يعمل بشكل أفضل مع الـ LLM الخاص بك.

كيف تتعامل مع إزالة التكرار في معالجات الـ webhook الخاصة بك؟ هل تستخدم Redis أم قيداً في قاعدة البيانات؟

المصدر: https://dev.to/qasim157/handle-messagecreated-webhooks-in-nextjs-4e80