Receber eventos do Slack no Jitterbit Studio

Introdução

A API de Eventos do Slack fornece notificações em tempo real para uma URL que você registra no seu app do Slack (por exemplo, sempre que um usuário publica uma mensagem em um canal). Para receber esses eventos no Studio, configure um endpoint do API Manager que aceite as requisições POST de entrada.

A API de Eventos do Slack tem dois requisitos que diferem de um webhook padrão:

• Verificação de URL: Quando você primeiro registra a URL do endpoint no seu app do Slack, o Slack envia uma requisição de desafio. O endpoint deve retornar o valor do desafio antes que o Slack entregue qualquer evento.
• Janela de resposta de 3 segundos: O Slack espera HTTP 200 dentro de 3 segundos após enviar um evento. Operações que realizam processamento significativo devem despachar esse trabalho de forma assíncrona e retornar imediatamente.

Este guia aborda como configurar o endpoint da API, lidar com a verificação de URL e receber eventos de entrada. Ele para no ponto em que a carga do evento é recebida e despachada para processamento. Para rotear a carga para operações posteriores, consulte Encadear e controlar operações. Para casos de uso de agentes de IA em que um LLM seleciona qual operação executar com base no evento, consulte Rotear respostas do LLM para operações do Studio usando chamada de função.

Este guia pressupõe o seguinte:

• Uma API customizada está configurada e publicada no API Manager no mesmo ambiente do projeto.
• Um app do Slack existe com Event Subscriptions ativado. Se você não tiver um, crie um app em api.slack.com/apps e ative Event Subscriptions nas configurações do app.
• Você está familiarizado com os passos básicos para criar endpoints de API customizada.

Parte 1: Criar o endpoint da API

Passo 1: Criar a API

1. Abra o API Manager e clique em New API.

2. Selecione Custom API como o tipo de API.

3. API Name: Digite um nome para a API (por exemplo, Slack Event Listener).

4. URL Prefix: Digite um segmento de caminho base para a URL do endpoint (por exemplo, slack).

5. Version: Digite uma string de versão (por exemplo, 1.0).

6. Enable SSL: Ative esta opção. O Slack só entrega eventos para endpoints HTTPS.

7. Clique em Save.

Passo 2: Configurar o endpoint de serviço

1. No editor de API, clique em Add Service.

2. Method: Selecione POST.

3. Path: Digite um caminho de endpoint (por exemplo, /events).

4. Operation: Selecione a operação do Studio que será executada quando um evento for recebido. Esta operação conterá o script do listener descrito nas Partes 2 e 3.

5. Response Type: Selecione System Variable.

6. Clique em Save, depois em Publish.

Após publicar, copie a URL do endpoint exibida pelo API Manager. Você inserirá esta URL nas configurações do app do Slack durante a etapa de verificação.

Parte 2: Lidar com verificação de URL

Quando você insere a URL do endpoint nas configurações de Event Subscriptions do seu app do Slack, o Slack imediatamente envia uma requisição POST para verificar se a URL pertence a você. O corpo da requisição contém um campo type configurado como url_verification e um campo challenge com um token aleatório. O endpoint deve retornar esse token no corpo da resposta.

Se o endpoint não responder corretamente, o Slack rejeita a URL e Event Subscriptions não pode ser ativado.

Adicione a seguinte verificação no início da operação do script do 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 analisa o corpo da requisição bruta em um dicionário. Get extrai campos individuais. Quando o tipo é url_verification, Dict cria um dicionário de resposta, JSONStringify o serializa para JSON, e Return sai do script para que nenhuma lógica de processamento de evento seja executada para esta requisição.

Parte 3: Receber mensagens de evento

Após a conclusão da verificação de URL, o Slack envia cargas de evento para toda atividade que corresponde aos tipos de evento aos quais você se inscreveu. Duas verificações adicionais são necessárias antes de enviar o evento para processamento.

Filtrar mensagens de bot

Se a integração publica mensagens de volta ao Slack (por exemplo, como parte de um agente de IA ou resposta automatizada), essas mensagens geram novos eventos que disparam a operação novamente. Isso cria um loop infinito. Filtre mensagens de bot antes de processar:

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

O Slack define event.bot_id em mensagens postadas por usuários bot. Se o campo estiver presente, o script reconhece o evento com HTTP 200 e sai sem processá-lo.

Enviar o processamento de forma assíncrona

O Slack cancela a entrega de evento e tenta novamente se o endpoint não responder em 3 segundos. Operações que chamam um LLM, consultam um banco de dados ou executam várias etapas normalmente excedem essa janela.

Execute a operação de processamento de forma assíncrona usando RunOperation com runSynchronously definido como false e defina a resposta imediatamente:

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

O parâmetro false informa ao Studio para não aguardar a conclusão da operação de processamento. O script do listener define a resposta 200 e sai em milissegundos, atendendo ao tempo limite do Slack. A operação de processamento é executada independentemente em segundo plano.

Para considerações sobre condições de corrida e limites de concorrência ao usar operações assíncronas, consulte Gerenciar operações assíncronas.

Script completo do listener

O script a seguir combina a verificação de URL, o filtro de bot e o envio assíncrono:

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

A carga do evento bruto permanece disponível para operações a jusante via $jitterbit.api.request.body. Para responder ao usuário ou publicar uma mensagem de volta ao Slack após o processamento, consulte Enviar uma notificação do Slack de uma operação do Studio.

Verificar a integração

1. Implante o projeto e confirme que o endpoint da API foi publicado no API Manager.

2. Nas configurações do seu app Slack, acesse Event Subscriptions e cole a URL do endpoint no campo Request URL. O Slack envia a solicitação de verificação de URL automaticamente.

3. Confirme que o campo Request URL mostra Verified. Se a verificação falhar, abra os logs de operação no Studio para verificar se há erros e confirme se a URL do endpoint está correta e se o projeto foi implantado.

4. Em Subscribe to Bot Events, adicione os tipos de evento que deseja receber (por exemplo, message.channels ou app_mention). Clique em Save Changes.

5. Reinstale o app no seu workspace se o Slack solicitar.

6. Poste uma mensagem em um canal Slack do qual o bot é membro.

7. Abra os logs de operação no Studio e confirme que a operação do listener foi executada e que a operação de processamento foi enviada.