Recibir eventos de Slack en Jitterbit Studio

Introducción

La API de eventos de Slack entrega notificaciones en tiempo real a una URL que registras en tu aplicación de Slack (por ejemplo, cada vez que un usuario publica un mensaje en un canal). Para recibir estos eventos en Studio, configuras un endpoint de API Manager que acepta las solicitudes POST entrantes.

La API de eventos de Slack tiene dos requisitos que difieren de un webhook estándar:

• Verificación de URL: Cuando registras por primera vez la URL del endpoint en tu aplicación de Slack, Slack envía una solicitud de desafío. El endpoint debe devolver el valor del desafío antes de que Slack entregue cualquier evento.
• Ventana de respuesta de 3 segundos: Slack espera HTTP 200 dentro de 3 segundos de enviar un evento. Las operaciones que realizan procesamiento significativo deben enviar ese trabajo de forma asincrónica y devolver inmediatamente.

Esta guía cubre cómo configurar el endpoint de API, manejar la verificación de URL y recibir eventos entrantes. Se detiene en el punto donde se recibe la carga útil del evento y se envía para procesamiento. Para enrutar la carga útil a operaciones posteriores, consulta Encadenar y controlar operaciones. Para casos de uso de agentes de IA donde un LLM selecciona qué operación ejecutar según el evento, consulta Enrutar respuestas de LLM a operaciones de Studio mediante function calling.

Esta guía asume lo siguiente:

• Se configura una API personalizada y se publica en API Manager en el mismo entorno que el proyecto.
• Existe una aplicación de Slack con Event Subscriptions habilitado. Si no tienes una, crea una aplicación en api.slack.com/apps y habilita Event Subscriptions en la configuración de la aplicación.
• Estás familiarizado con los pasos básicos para crear endpoints de API personalizados.

Parte 1: Crear el endpoint de API

Paso 1: Crear la API

1. Abre API Manager y haz clic en New API.

2. Selecciona Custom API como el tipo de API.

3. API Name: Ingresa un nombre para la API (por ejemplo, Slack Event Listener).

4. URL Prefix: Ingresa un segmento de ruta base para la URL del endpoint (por ejemplo, slack).

5. Version: Ingresa una cadena de versión (por ejemplo, 1.0).

6. Enable SSL: Habilita esta opción. Slack solo entrega eventos a endpoints HTTPS.

7. Haz clic en Save.

Paso 2: Configurar el endpoint de servicio

1. En el editor de API, haz clic en Add Service.

2. Method: Selecciona POST.

3. Path: Ingresa una ruta de endpoint (por ejemplo, /events).

4. Operation: Selecciona la operación de Studio que se ejecutará cuando se reciba un evento. Esta operación contendrá el script de escucha descrito en las Partes 2 y 3.

5. Response Type: Selecciona System Variable.

6. Haz clic en Save, luego haz clic en Publish.

Después de publicar, copia la URL del endpoint que muestra API Manager. Ingresarás esta URL en la configuración de la aplicación de Slack durante el paso de verificación.

Parte 2: Manejar la verificación de URL

Cuando ingresas la URL del endpoint en la configuración de Event Subscriptions de tu aplicación de Slack, Slack inmediatamente envía una solicitud POST para verificar que la URL te pertenece. El cuerpo de la solicitud contiene un campo type establecido en url_verification y un campo challenge con un token aleatorio. El endpoint debe devolver ese token en el cuerpo de la respuesta.

Si el endpoint no responde correctamente, Slack rechaza la URL y Event Subscriptions no se puede habilitar.

Agrega la siguiente verificación al inicio de la operación del script de escucha:

<trans>
$body = JSONParser($jitterbit.api.request.body);
$type = Get($body, "type");

If($type == "url_verification",
  $challenge_response = Dict();
  $challenge_response["challenge"] = Get($body, "challenge");
  $jitterbit.api.response = JSONStringify($challenge_response);
  $jitterbit.api.response.status_code = 200;
  Return();
);
</trans>

JSONParser analiza el cuerpo de la solicitud sin procesar en un diccionario. Get extrae campos individuales. Cuando el tipo es url_verification, Dict crea un diccionario de respuesta, JSONStringify lo serializa a JSON, y Return sale del script para que no se ejecute lógica de procesamiento de eventos para esta solicitud.

Parte 3: Recibir mensajes de evento

Después de completar la verificación de URL, Slack envía cargas de evento para toda la actividad que coincida con los tipos de evento a los que te suscribiste. Se requieren dos verificaciones adicionales antes de enviar el evento para procesamiento.

Filtrar mensajes de bot

Si tu integración publica mensajes de vuelta en Slack (por ejemplo, como parte de un agente de IA o respuesta automatizada), esos mensajes generan nuevos eventos que disparan la operación nuevamente. Esto crea un bucle infinito. Filtra los mensajes de bot antes de procesarlos:

<trans>
$botId = Get($body, "event.bot_id");
If(Length($botId) > 0,
  $jitterbit.api.response.status_code = 200;
  $jitterbit.api.response = "";
  Return();
);
</trans>

Slack establece event.bot_id en los mensajes publicados por usuarios bot. Si el campo está presente, el script reconoce el evento con HTTP 200 y sale sin procesarlo.

Enviar procesamiento de forma asincrónica

Slack cancela la entrega de eventos y reintentos si el endpoint no responde dentro de 3 segundos. Las operaciones que llaman a un LLM, consultan una base de datos o realizan múltiples pasos típicamente excederán esta ventana.

Ejecuta la operación de procesamiento de forma asincrónica usando RunOperation con runSynchronously establecido en false, luego establece la respuesta inmediatamente:

<trans>
RunOperation("<TAG>operation:Process Slack Event</TAG>", false);
$jitterbit.api.response.status_code = 200;
$jitterbit.api.response = "";
</trans>

El parámetro false le indica a Studio que no espere a que se complete la operación de procesamiento. El script del listener establece la respuesta 200 y sale en milisegundos, satisfaciendo el tiempo de espera de Slack. La operación de procesamiento se ejecuta independientemente en segundo plano.

Para consideraciones sobre condiciones de carrera y límites de concurrencia al usar operaciones asincrónicas, consulta Manage asynchronous operations.

Script del listener completo

El siguiente script combina la verificación de URL, el filtro de bot y el envío asincrónico:

<trans>
$body = JSONParser($jitterbit.api.request.body);
$type = Get($body, "type");

// Handle Slack URL verification challenge
If($type == "url_verification",
  $challenge_response = Dict();
  $challenge_response["challenge"] = Get($body, "challenge");
  $jitterbit.api.response = JSONStringify($challenge_response);
  $jitterbit.api.response.status_code = 200;
  Return();
);

// Ignore messages from bots to prevent loops
$botId = Get($body, "event.bot_id");
If(Length($botId) > 0,
  $jitterbit.api.response.status_code = 200;
  $jitterbit.api.response = "";
  Return();
);

// Dispatch event processing asynchronously and respond immediately
RunOperation("<TAG>operation:Process Slack Event</TAG>", false);
$jitterbit.api.response.status_code = 200;
$jitterbit.api.response = "";
</trans>

La carga de evento sin procesar permanece disponible para operaciones posteriores a través de $jitterbit.api.request.body. Para responder al usuario o publicar un mensaje de vuelta en Slack después del procesamiento, consulta Send a Slack notification from a Studio operation.

Verificar la integración

1. Despliega el proyecto y confirma que el endpoint de API se publica en API Manager.

2. En la configuración de tu aplicación Slack, ve a Event Subscriptions y pega la URL del endpoint en el campo Request URL. Slack envía la solicitud de verificación de URL automáticamente.

3. Confirma que el campo Request URL muestra Verified. Si la verificación falla, abre los operation logs en Studio para verificar errores y confirma que la URL del endpoint es correcta y que el proyecto está desplegado.

4. En Subscribe to Bot Events, agrega los tipos de evento que deseas recibir (por ejemplo, message.channels o app_mention). Haz clic en Save Changes.

5. Reinstala la aplicación en tu workspace si Slack te lo solicita.

6. Publica un mensaje en un canal de Slack del que el bot sea miembro.

7. Abre los operation logs en Studio y confirma que la operación del listener se ejecutó y que la operación de procesamiento fue enviada.