Kelola Webhook Nylas di Next.js

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

Sebuah email masuk ke agen AI Anda. Anda punya waktu 10 detik untuk merespons.

Jika Anda menggunakan Nylas Agent Accounts, webhook message.created akan langsung masuk ke server Anda. Di Next.js, Anda dapat menanganinya hanya dengan satu file route.

Berikut cara membangunnya dengan benar.

𝗧𝗮𝗻𝘁𝗮𝗻𝗴𝗮𝗻 𝗛𝗮𝗻𝗱𝘀𝗵𝗮𝗸𝗲

Saat Anda membuat webhook, Nylas mengirimkan permintaan GET dengan parameter challenge. Anda harus mengembalikan nilai yang sama persis di dalam body respons.

Jangan gunakan JSON. Jangan tambahkan tanda kutip. Gunakan bare response. Jika Anda gagal melakukan ini, webhook akan gagal.

Contoh handler GET:

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

𝗡𝗼𝘁𝗶𝗳𝗶𝗸𝗮𝘀𝗶 𝗣𝗢𝗦𝗧

Saat sebuah pesan tiba, Nylas mengirimkan permintaan POST. Ikuti tiga aturan ini untuk menghindari error:

• Berikan konfirmasi segera. Kembalikan status 200 sebelum menjalankan logika berat Anda. Jika LLM Anda memakan waktu terlalu lama, webhook akan mengalami timeout.
• Verifikasi tanda tangan. Gunakan header X-Nylas-Signature dan webhook secret Anda. Ini mencegah pengguna yang tidak berwenang memicu agen Anda.
• Gunakan raw body. Untuk memverifikasi tanda tangan HMAC, Anda memerlukan teks mentah. Baca teksnya terlebih dahulu, verifikasi, lalu parse JSON-nya.

Contoh handler 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 });
}

𝗧𝗶𝗽𝘀 𝗣𝗿𝗼𝗱𝘂𝗸𝘀𝗶

• Lakukan deduplikasi pesan. Webhook mengirimkan setidaknya satu kali (at-least-once). Gunakan database constraint atau Redis untuk memastikan Anda tidak memproses pesan yang sama dua kali. • Tangani payload yang terpotong. Jika pesan lebih dari 1 MB, bagian body akan dipotong. Selalu ambil ulang (re-fetch) pesan melalui API untuk mendapatkan konten lengkapnya. • Gunakan konten yang sudah dibersihkan. Gunakan message.created.cleaned untuk mendapatkan markdown alih-alih HTML yang berantakan. Ini bekerja lebih baik untuk LLM Anda.

Bagaimana Anda menangani deduplikasi dalam webhook handler Anda? Apakah Anda menggunakan Redis atau database constraint?

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