Gérer les webhooks Nylas dans Next.js

Gérer les webhooks Nylas dans Next.js

Un e-mail arrive sur votre agent IA. Vous avez 10 secondes pour répondre.

Si vous utilisez les Nylas Agent Accounts, un webhook message.created atteint votre serveur immédiatement. Dans Next.js, vous gérez cela avec un seul fichier de route.

Voici comment le construire correctement.

Le handshake du challenge

Lorsque vous créez un webhook, Nylas envoie une requête GET avec un paramètre challenge. Vous devez renvoyer la valeur exacte dans le corps de la réponse.

N'utilisez pas de JSON. N'ajoutez pas de guillemets. Utilisez une réponse brute (bare response). Si vous échouez à cette étape, le webhook échouera.

Exemple de gestionnaire GET :

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

La notification POST

Lorsqu'un message arrive, Nylas envoie une requête POST. Suivez ces trois règles pour éviter les erreurs :

• Accusez réception immédiatement. Renvoyez un statut 200 avant d'exécuter votre logique lourde. Si votre LLM met trop de temps, le webhook expirera (timeout).
• Vérifiez les signatures. Utilisez l'en-tête X-Nylas-Signature et votre secret de webhook. Cela empêche les utilisateurs non autorisés de déclencher votre agent.
• Utilisez le corps brut (raw body). Pour vérifier la signature HMAC, vous avez besoin du texte brut. Lisez d'abord le texte, vérifiez-le, puis analysez (parse) le JSON.

Exemple de gestionnaire 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 });
}

Conseils de production

• Éliminez les doublons de messages. Les webhooks sont livrés au moins une fois (at-least-once). Utilisez une contrainte de base de données ou Redis pour vous assurer de ne pas traiter deux fois le même message. • Gérez les charges utiles tronquées. Si un message dépasse 1 Mo, le corps est tronqué. Récupérez toujours à nouveau le message via l'API pour obtenir l'intégralité du contenu. • Utilisez le contenu nettoyé. Utilisez message.created.cleaned pour obtenir du markdown plutôt qu'un HTML mal formaté. Cela fonctionne mieux pour votre LLM.

Comment gérez-vous la déduplication dans vos gestionnaires de webhooks ? Utilisez-vous Redis ou une contrainte de base de données ?

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