Monitorar eventos do Experience Platform no Slack

Saiba como receber notificações do Experience Platform no Slack integrando com um proxy de webhook do Adobe App Builder. Engenheiros de dados e administradores podem querer receber notificações proativas no Slack da Adobe Experience Platform para monitorar a integridade de suas implementações da plataforma. Este tutorial descreve as etapas de arquitetura e implementação para conectar o Adobe I/O Events ao Slack usando o Adobe App Builder.

Por que um proxy de webhook?

Não é possível conectar diretamente o Adobe I/O Events a um Webhook de entrada do Slack devido a uma incompatibilidade de protocolo no processo de verificação.

Visão geral da arquitetura

O que é o Adobe Developer Console?

O Adobe Developer Console é o portal central para gerenciar projetos, APIs e credenciais da Adobe. É onde você cria seu projeto, configura a autenticação e registra seus webhooks.

O que é o App Builder?

O Adobe App Builder é uma estrutura completa que permite que desenvolvedores corporativos criem aplicativos nativos em nuvem.

O que é o Adobe I/O Runtime?

O Adobe I/O Runtime é a plataforma sem servidor que capacita o App Builder. Ele permite que os desenvolvedores implantem o código (Funções como um serviço) executado em resposta a solicitações HTTP sem gerenciar a infraestrutura do servidor.

Nesta implementação, usamos uma Ação. Uma ação é uma função sem estado (escrita em Node.js) executada no Adobe I/O Runtime. Nossa Ação serve como o endpoint HTTP público com o qual o Adobe I/O Events se comunica.

Para obter mais informações, consulte a documentação do Adobe I/O Runtime.

Guia de implementação

Pré-requisitos

Antes de iniciar, verifique se você tem o seguinte:

Etapa 1: criar um projeto no Adobe Developer Console

Primeiro, crie um projeto com o modelo App Builder no Adobe Developer Console:

Inicializar o ambiente de tempo de execução

Execute os seguintes comandos no terminal para criar a estrutura do projeto:

Fazer logon em aio

aio login

Etapa 2: inicializar um novo projeto do App Builder

aio app init slack-webhook-proxy

A inicialização do aplicativo deve ser concluída.

Navegue até o diretório do projeto

cd slack-webhook-proxy

Adicionar a ação da Web

aio app add action

Etapa 3: atualizar o código de ação de proxy

Em um editor de texto ou IDE, crie/modifique o arquivo actions/webhook-proxy/index.js com o seguinte código. Essa implementação encaminha eventos para o Slack. A verificação de assinatura e o tratamento de desafio são automáticos ao usar o registro de Ação em tempo de execução.

const fetch = require("node-fetch");
const { Core } = require("@adobe/aio-sdk");

/**
 * Adobe I/O Events to Slack Runtime Proxy
 *
 * Receives events from Adobe I/O Events and forwards them to Slack.
 * Signature verification and challenge handling are automatic when
 * using Runtime Action registration (non-web action).
 */
async function main(params) {
  const logger = Core.Logger("webhook-proxy", { level: params.LOG_LEVEL || "info" });

  try {
    logger.info(`Event received: ${JSON.stringify(params)}`);

    // Forward to Slack
    return forwardToSlack(params, params.SLACK_WEBHOOK_URL, logger);

  } catch (error) {
    logger.error(`Error: ${error.message}`);
    return { statusCode: 500, body: { error: "Internal server error" } };
  }
}

/**
 * Forwards the event payload to Slack
 */
async function forwardToSlack(payload, webhookUrl, logger) {
  if (!webhookUrl) {
    logger.error("SLACK_WEBHOOK_URL not configured");
    return { statusCode: 500, body: { error: "Server configuration error" } };
  }

  // Extract Adobe headers passed to runtime action
  const headers = {
    "x-adobe-event-code": payload["x-adobe-event-code"],
    "x-adobe-event-id": payload["x-adobe-event-id"],
    "x-adobe-provider": payload["x-adobe-provider"]
  };

  const slackMessage = buildSlackMessage(payload, headers);

  const response = await fetch(webhookUrl, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(slackMessage)
  });

  if (!response.ok) {
    const errorText = await response.text();
    logger.error(`Slack API error: ${response.status} - ${errorText}`);
    return { statusCode: response.status, body: { error: errorText } };
  }

  logger.info("Event forwarded to Slack");
  return { statusCode: 200, body: { success: true } };
}

/**
 * Builds a Slack Block Kit message from the event payload
 */
function buildSlackMessage(payload, headers) {
  // Adobe passes event code as x-adobe-event-code header (available in params for runtime actions)
  const eventType = headers["x-adobe-event-code"] ||
                    payload["x-adobe-event-code"] ||
                    payload.event_code ||
                    payload.type ||
                    payload.event_type ||
                    "Adobe Event";
  const eventId = headers["x-adobe-event-id"] || payload["x-adobe-event-id"] || payload.event_id || payload.id || "N/A";
  const eventData = payload.data || payload.event || payload;

  return {
    blocks: [
      {
        type: "header",
        text: { type: "plain_text", text: `Event: ${eventType}`, emoji: true }
      },
      {
        type: "section",
        fields: formatDataFields(eventData)
      },
      { type: "divider" },
      {
        type: "context",
        elements: [{
          type: "mrkdwn",
          text: `*Event ID:* ${eventId}  |  *Time:* ${new Date().toISOString()}`
        }]
      }
    ]
  };
}

/**
 * Formats event data as Slack mrkdwn fields
 */
function formatDataFields(data, maxFields = 10) {
  if (typeof data !== "object" || data === null) {
    return [{ type: "mrkdwn", text: `*Payload:*\n${String(data)}` }];
  }

  const entries = Object.entries(data);
  if (entries.length === 0) {
    return [{ type: "mrkdwn", text: "_No data provided_" }];
  }

  return entries.slice(0, maxFields).map(([key, value]) => ({
    type: "mrkdwn",
    text: `*${key}:*\n${typeof value === "object" ? `\`\`\`${JSON.stringify(value)}\`\`\`` : value}`
  }));
}

exports.main = main;

Etapa 4: configurar a ação

A configuração da ação em app.config.yaml é crítica. Usar web: não para criar uma ação que não seja da Web que possa ser registrada como uma Ação em tempo de execução no Developer Console.

application:
  runtimeManifest:
    packages:
      slack-webhook-proxy:
        license: Apache-2.0
        actions:
          webhook-proxy:
            function: actions/webhook-proxy/index.js
            web: no
            runtime: nodejs:22
            inputs:
              LOG_LEVEL: info
              SLACK_WEBHOOK_URL: $SLACK_WEBHOOK_URL
            annotations:
              require-adobe-auth: false
              final: true

Por que web: no?

Ao usar uma ação que não seja da Web e registrá-la por meio da opção "Ação em tempo de execução" no Developer Console, o Adobe I/O Events automaticamente:

Isso significa que seu código só precisa lidar com a lógica de negócios (encaminhamento para o Slack).

Etapa 4: atualizar as variáveis de ambiente

Para gerenciar credenciais com segurança, usamos variáveis de ambiente. Crie/modifique o arquivo .env na raiz do seu projeto para adicionar a URL do webhook do Slack. Certifique-se de mostrar os arquivos ocultos no sistema se você não visualizar o arquivo .env:

# ... other .env file content ...

SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

Etapa 5: implantar a ação

Depois que as variáveis de ambiente forem definidas, implante a ação. Certifique-se de estar na raiz do seu projeto, ou seja, slack-webhook-proxy, ao executar este comando no terminal.

aio app deploy

Sua ação é implantada no Adobe I/O Runtime e está disponível na Developer Console para registro.

Etapa 6: registrar a ação no Adobe Developer Console

Agora que sua ação foi implantada, registre-a como destino para Eventos da Adobe.

Etapa 7: validar com um evento de amostra

Você pode testar todo o fluxo de ponta a ponta clicando no ícone 'Enviar evento de amostra' ao lado de qualquer evento configurado.

O evento de amostra é enviado no canal que você configurou ao criar seu aplicativo Slack e o webhook; Você deve ver algo semelhante ao seguinte:

Parabéns, você integrou o Slack com êxito aos eventos do Experience Platform!

Problemas comuns

Estes são alguns problemas que você pode ter ao configurar o proxy e algumas maneiras potenciais de resolvê-los.