مدیریت Webhookهای Nylas در Next.js

یک ایمیل به عامل هوش مصنوعی (AI agent) شما می‌رسد. شما ۱۰ ثانیه فرصت دارید تا پاسخ دهید.

اگر از Nylas Agent Accounts استفاده می‌کنید، یک webhook از نوع message.created بلافاصله به سرور شما ارسال می‌شود. در Next.js، شما این کار را تنها با یک فایل route مدیریت می‌کنید.

در اینجا نحوه پیاده‌سازی صحیح آن آمده است.

مرحله 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 ارسال می‌کند. برای جلوگیری از خطا، این سه قانون را رعایت کنید:

نمونه هندلر 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)

• حذف پیام‌های تکراری. وب‌هوک‌ها پیام‌ها را با تضمین «حداقل یک بار» (at-least-once) ارسال می‌کنند. از یک محدودیت پایگاه داده (database constraint) یا Redis استفاده کنید تا مطمئن شوید یک پیام را دو بار پردازش نمی‌کنید. • مدیریت محتواهای ناقص (truncated payloads). اگر حجم پیام بیش از ۱ مگابایت باشد، بدنه آن حذف می‌شود. همیشه برای دریافت محتوای کامل، پیام را مجدداً از طریق API فراخوانی کنید. • استفاده از محتوای پاک‌سازی‌شده. از message.created.cleaned برای دریافت markdown به جای HTML نامنظم استفاده کنید. این کار برای LLM شما بهتر عمل می‌کند.

شما چگونه حذف پیام‌های تکراری را در هندلرهای وب‌هوک خود مدیریت می‌کنید؟ آیا از Redis استفاده می‌کنید یا از محدودیت پایگاه داده؟

منبع: https://dev.to/qasim157/handle-messagecreated-webhooks-in-nextjs-4e80