Maneja webhooks de Nylas en Next.js

Maneja los webhooks de Nylas en Next.js

Un correo electrónico llega a tu agente de IA. Tienes 10 segundos para responder.

Si usas Nylas Agent Accounts, un webhook message.created llega a tu servidor de inmediato. En Next.js, manejas esto con un solo archivo de ruta.

Aquí te mostramos cómo construirlo correctamente.

El Challenge Handshake

Cuando creas un webhook, Nylas envía una solicitud GET con un parámetro challenge. Debes devolver el valor exacto en el cuerpo de la respuesta.

No uses JSON. No añadas comillas. Usa una respuesta simple (bare response). Si fallas en esto, el webhook fallará.

Ejemplo de manejador GET:

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

La notificación POST

Cuando llega un mensaje, Nylas envía una solicitud POST. Sigue estas tres reglas para evitar errores:

• Confirma la recepción de inmediato. Devuelve un estado 200 antes de ejecutar tu lógica pesada. Si tu LLM tarda demasiado, el webhook expirará por tiempo de espera (timeout).
• Verifica las firmas. Usa el encabezado X-Nylas-Signature y tu secreto de webhook. Esto evita que usuarios no autorizados activen tu agente.
• Usa el cuerpo en bruto (raw body). Para verificar la firma HMAC, necesitas el texto original. Lee el texto primero, verifícalo y luego analiza (parse) el JSON.

Ejemplo de manejador 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 });
}

Consejos para producción

• Elimina los mensajes duplicados. Los webhooks se entregan al menos una vez. Utiliza una restricción de base de datos o Redis para asegurar que no proceses el mismo mensaje dos veces. • Gestiona los payloads truncados. Si un mensaje supera 1 MB, el cuerpo se recorta. Vuelve a solicitar siempre el mensaje a través de la API para obtener el contenido completo. • Utiliza contenido limpio. Usa message.created.cleaned para obtener markdown en lugar de un HTML desordenado. Esto funciona mejor para tu LLM.

¿Cómo gestionas la eliminación de duplicados en tus manejadores de webhooks? ¿Utilizas Redis o una restricción de base de datos?

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