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

Next.js ਵਿੱਚ Nylas Webhooks ਨੂੰ ਹੈਂਡਲ ਕਰੋ

ਤੁਹਾਡੇ AI agent ਕੋਲ ਇੱਕ ਈਮੇਲ ਆਉਂਦੀ ਹੈ। ਤੁਹਾਡੇ ਕੋਲ ਜਵਾਬ ਦੇਣ ਲਈ 10 ਸਕਿੰਟ ਹਨ।

ਜੇਕਰ ਤੁਸੀਂ Nylas Agent Accounts ਦੀ ਵਰਤੋਂ ਕਰਦੇ ਹੋ, ਤਾਂ ਇੱਕ message.created webhook ਤੁਰੰਤ ਤੁਹਾਡੇ ਸਰਵਰ 'ਤੇ ਆਉਂਦਾ ਹੈ। Next.js ਵਿੱਚ, ਤੁਸੀਂ ਇਸਨੂੰ ਇੱਕ ਰੂਟ ਫਾਈਲ (route file) ਨਾਲ ਹੈਂਡਲ ਕਰ ਸਕਦੇ ਹੋ।

ਇਸਨੂੰ ਸਹੀ ਤਰੀਕੇ ਨਾਲ ਬਣਾਉਣ ਦਾ ਤਰੀਕਾ ਇੱਥੇ ਦਿੱਤਾ ਗਿਆ ਹੈ।

ਚੈਲੇਂਜ ਹੈਂਡਸ਼ੇਕ (The Challenge Handshake)

ਜਦੋਂ ਤੁਸੀਂ ਇੱਕ webhook ਬਣਾਉਂਦੇ ਹੋ, ਤਾਂ Nylas ਇੱਕ challenge ਪੈਰਾਮੀਟਰ ਦੇ ਨਾਲ GET ਰਿਕੁਐਸਟ ਭੇਜਦਾ ਹੈ। ਤੁਹਾਨੂੰ ਰਿਸਪਾਂਸ ਬਾਡੀ (response body) ਵਿੱਚ ਬਿਲਕੁਲ ਉਹੀ ਵੈਲਯੂ ਵਾਪਸ ਕਰਨੀ ਚਾਹੀਦੀ ਹੈ।

JSON ਦੀ ਵਰਤੋਂ ਨਾ ਕਰੋ। ਕੋਟਸ (quotes) ਨਾ ਲਗਾਓ। ਇੱਕ ਬੇਅਰ ਰਿਸਪਾਂਸ (bare response) ਦੀ ਵਰਤੋਂ ਕਰੋ। ਜੇਕਰ ਤੁਸੀਂ ਇਹ ਕਰਨ ਵਿੱਚ ਅਸਫਲ ਰਹਿੰਦੇ ਹੋ, ਤਾਂ webhook ਫੇਲ ਹੋ ਜਾਵੇਗਾ।

Example GET handler:

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

POST ਨੋਟੀਫਿਕੇਸ਼ਨ

ਜਦੋਂ ਕੋਈ ਮੈਸੇਜ ਆਉਂਦਾ ਹੈ, ਤਾਂ Nylas ਇੱਕ POST ਰਿਕੁਐਸਟ ਭੇਜਦਾ ਹੈ। ਗਲਤੀਆਂ ਤੋਂ ਬਚਣ ਲਈ ਇਹਨਾਂ ਤਿੰਨ ਨਿਯਮਾਂ ਦੀ ਪਾਲਣਾ ਕਰੋ:

• ਤੁਰੰਤ ਐਕਨੌਲੇਜ (Acknowledge) ਕਰੋ। ਆਪਣੀ ਹੈਵੀ ਲੌਜਿਕ (heavy logic) ਚਲਾਉਣ ਤੋਂ ਪਹਿਲਾਂ 200 ਸਟੇਟਸ ਵਾਪਸ ਕਰੋ। ਜੇਕਰ ਤੁਹਾਡਾ LLM ਬਹੁਤ ਜ਼ਿਆਦਾ ਸਮਾਂ ਲੈਂਦਾ ਹੈ, ਤਾਂ webhook ਦਾ ਸਮਾਂ ਖਤਮ (time out) ਹੋ ਜਾਵੇਗਾ।
• ਸਿਗਨੇਚਰਾਂ ਦੀ ਪੜਤਾਲ ਕਰੋ। X-Nylas-Signature ਹੈਡਰ ਅਤੇ ਆਪਣੇ webhook secret ਦੀ ਵਰਤੋਂ ਕਰੋ। ਇਹ ਅਣਅਧਿਕਾਰਤ ਯੂਜ਼ਰਾਂ ਨੂੰ ਤੁਹਾਡੇ agent ਨੂੰ ਟ੍ਰਿਗਰ ਕਰਨ ਤੋਂ ਰੋਕਦਾ ਹੈ।
• ਰੋਅ ਬਾਡੀ (raw body) ਦੀ ਵਰਤੋਂ ਕਰੋ। HMAC ਸਿਗਨੇਚਰ ਦੀ ਪੜਤਾਲ ਕਰਨ ਲਈ, ਤੁਹਾਨੂੰ ਰੋਅ ਟੈਕਸਟ ਦੀ ਲੋੜ ਹੁੰਦੀ ਹੈ। ਪਹਿਲਾਂ ਟੈਕਸਟ ਪੜ੍ਹੋ, ਇਸਦੀ ਪੜਤਾਲ ਕਰੋ, ਫਿਰ JSON ਨੂੰ ਪਾਰਸ (parse) ਕਰੋ।

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

ਪ੍ਰੋਡਕਸ਼ਨ ਟਿਪਸ (Production Tips)

• ਮੈਸੇਜਾਂ ਦੀ ਡੁਪਲੀਕੇਸ਼ਨ ਰੋਕੋ। Webhooks ਘੱਟੋ-ਘੱਟ ਇੱਕ ਵਾਰ ਡਿਲੀਵਰ ਕਰਦੇ ਹਨ। ਇਹ ਯਕੀਨੀ ਬਣਾਉਣ ਲਈ ਕਿ ਤੁਸੀਂ ਇੱਕੋ ਮੈਸੇਜ ਨੂੰ ਦੋ ਵਾਰ ਪ੍ਰੋਸੈਸ ਨਾ ਕਰੋ, ਡਾਟਾਬੇਸ ਕੰਸਟ੍ਰੇਂਟ ਜਾਂ Redis ਦੀ ਵਰਤੋਂ ਕਰੋ। • ਟ੍ਰੰਕੇਟ ਕੀਤੇ (truncated) payloads ਨੂੰ ਸੰਭਾਲੋ। ਜੇਕਰ ਕੋਈ ਮੈਸੇਜ 1 MB ਤੋਂ ਵੱਧ ਹੈ, ਤਾਂ ਉਸਦੀ body ਹਟਾ ਦਿੱਤੀ ਜਾਂਦੀ ਹੈ। ਪੂਰਾ ਕੰਟੈਂਟ ਪ੍ਰਾਪਤ ਕਰਨ ਲਈ ਹਮੇਸ਼ਾ API ਰਾਹੀਂ ਮੈਸੇਜ ਨੂੰ ਦੁਬਾਰਾ fetch ਕਰੋ। • ਸਾਫ਼ (cleaned) ਕੰਟੈਂਟ ਦੀ ਵਰਤੋਂ ਕਰੋ। ਗੰਦਮੇ HTML ਦੀ ਬਜਾਏ markdown ਪ੍ਰਾਪਤ ਕਰਨ ਲਈ message.created.cleaned ਦੀ ਵਰਤੋਂ ਕਰੋ। ਇਹ ਤੁਹਾਡੇ LLM ਲਈ ਬਿਹਤਰ ਕੰਮ ਕਰਦਾ ਹੈ।

ਤੁਸੀਂ ਆਪਣੇ webhook handlers ਵਿੱਚ deduplication ਨੂੰ ਕਿਵੇਂ ਸੰਭਾਲਦੇ ਹੋ? ਕੀ ਤੁਸੀਂ Redis ਜਾਂ ਡਾਟਾਬੇਸ ਕੰਸਟ੍ਰੇਂਟ ਦੀ ਵਰਤੋਂ ਕਰਦੇ ਹੋ?

ਸਰੋਤ: https://dev.to/qasim157/handle-messagecreated-webhooks-in-nextjs-4e80