Recibir eventos de Slack en Jitterbit Studio

Introducción

La API de eventos de Slack entrega notificaciones en tiempo real a una URL que registres 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, configura un endpoint de API Manager que acepte 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 registres 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 de eventos y se envía para procesamiento. Para enrutar la carga a operaciones posteriores, consulta Encadenar y controlar operaciones. Para casos de uso de agentes de IA donde un LLM selecciona qué operación ejecutar basándose en el evento, consulta Enrutar respuestas de LLM a operaciones de Studio mediante function calling.

Esta guía asume lo siguiente:

• Una API personalizada está configurada y publicada en API Manager en el mismo ambiente que el proyecto.
• Existe una aplicación de Slack con Event Subscriptions habilitada. 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 personalizada.

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 listener 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 ingreses 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 puede habilitarse.

Añade la siguiente verificación al principio de la operación del script listener:

<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 eventos

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

Filtrar mensajes de bots

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

<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 en 3 segundos. Las operaciones que llaman a un LLM, consultan una base de datos o realizan varios pasos típicamente excederán esta ventana.

Ejecuta la operación de procesamiento de forma asincrónica utilizando 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 de escucha establece la respuesta 200 y sale en milisegundos, satisfaciendo el tiempo de espera de Slack. La operación de procesamiento se ejecuta de forma independiente en segundo plano.

Para consideraciones sobre condiciones de carrera y límites de concurrencia al utilizar operaciones asincrónicas, consulta Gestionar operaciones asincrónicas.

Script de escucha completo

El siguiente script combina la verificación de URL, el filtro de bots 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 descendentes a través de $jitterbit.api.request.body. Para responder al usuario o publicar un mensaje nuevamente en Slack después del procesamiento, consulta Enviar una notificación de Slack desde una operación de Studio.

Verificar la integración

1. Implementa el proyecto y confirma que el endpoint de API está publicado en API Manager.

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

3. Confirma que el campo Request URL muestre Verified (Verificado). Si la verificación falla, abre los registros de operación en Studio para verificar si hay errores y confirma que la URL del endpoint sea correcta y que el proyecto esté implementado.

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

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 registros de operación en Studio y confirma que la operación de escucha se ejecutó y que la operación de procesamiento se envió.