Monitorare gli eventi di Experience Platform in Slack

Scopri come ricevere le notifiche di Experience Platform in Slack tramite l’integrazione con un proxy webhook di Adobe App Builder. I data engineer e gli amministratori potrebbero voler ricevere notifiche proattive in Slack da Adobe Experience Platform per monitorare lo stato delle loro implementazioni di Platform. Questo tutorial illustra l’architettura e i passaggi di implementazione per collegare Adobe I/O Events a Slack utilizzando Adobe App Builder.

Perché un proxy webhook?

La connessione diretta di Adobe I/O Events a un webhook in ingresso Slack non è possibile a causa di una mancata corrispondenza del protocollo nel processo di verifica.

Panoramica dell’architettura

Cos’è Adobe Developer Console?

Adobe Developer Console è il portale centrale per la gestione dei progetti Adobe, delle API e delle credenziali. È dove puoi creare il progetto, configurare l’autenticazione e registrare i webhook.

Cos’è App Builder?

Adobe App Builder è un framework completo che consente agli sviluppatori aziendali di creare applicazioni native per il cloud.

Cos’è Adobe I/O Runtime?

Adobe I/O Runtime è la piattaforma senza server che alimenta App Builder. Consente agli sviluppatori di implementare il codice (Functions-as-a-Service) che viene eseguito in risposta alle richieste HTTP senza gestire l’infrastruttura del server.

In questa implementazione viene utilizzata un'azione Action. Un’azione è una funzione senza stato (scritta in Node.js) che viene eseguita sul Adobe I/O Runtime. La nostra azione funge da endpoint HTTP pubblico con cui Adobe I/O Events comunica.

Per ulteriori informazioni, consulta la documentazione di Adobe I/O Runtime.

Guida all’implementazione

Prerequisiti

Prima di iniziare, assicurati di disporre dei seguenti elementi:

Passaggio 1: creare un progetto in Adobe Developer Console

Innanzitutto, crea un progetto con il modello App Builder in Adobe Developer Console:

Inizializzare l’ambiente di runtime

Esegui i seguenti comandi nel terminale per creare la struttura del progetto:

Accedi a aio

aio login

Passaggio 2: inizializzare un nuovo progetto App Builder

aio app init slack-webhook-proxy

L'inizializzazione dell'app dovrebbe essere completata.

Passa alla directory del progetto

cd slack-webhook-proxy

Aggiungi l’azione web

aio app add action

Passaggio 3: aggiornare il codice dell’azione proxy

In un IDE o in un editor di testo, creare/modificare il file actions/webhook-proxy/index.js con il codice seguente. Questa implementazione inoltra gli eventi a Slack. La verifica della firma e la gestione della verifica della verifica sono automatiche quando si utilizza la registrazione delle azioni di runtime.

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;

Passaggio 4: configurare l’azione

La configurazione dell'azione in app.config.yaml è critica. Utilizza web: no per creare un’azione non web che può essere registrata come azione di runtime in 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

Perché web: no?

Quando utilizzi un’azione non web e la registri tramite l’opzione "Azione runtime" in Developer Console, Adobe I/O Events automaticamente:

Questo significa che il codice deve gestire solo la logica di business (inoltro a Slack).

Passaggio 4: aggiornare le variabili di ambiente

Per gestire in modo sicuro le credenziali, vengono utilizzate le variabili di ambiente. Crea/modifica il file .env nella directory principale del progetto per aggiungere l'URL del webhook di Slack. Assicurarsi di visualizzare i file nascosti nel sistema se il file .env non è visualizzato:

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

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

Passaggio 5: distribuire l’azione

Una volta impostate le variabili di ambiente, distribuisci l’azione. Assicurati di trovarti nella directory principale del progetto, ovvero slack-webhook-proxy, quando esegui questo comando nel terminale.

aio app deploy

L'azione viene distribuita in Adobe I/O Runtime ed è disponibile in Developer Console per la registrazione.

Passaggio 6: registrare l’azione in Adobe Developer Console

Una volta implementata l’azione, registrala come destinazione per gli eventi Adobe.

Passaggio 7: convalidare con un evento di esempio

Puoi verificare l’intero flusso end-to-end facendo clic sull’icona "Invia evento di esempio" accanto a qualsiasi evento configurato.

L’evento di esempio viene inviato sul canale configurato durante la creazione dell’app Slack e del webhook. Dovresti trovare qualcosa di simile al seguente:

Congratulazioni, hai integrato correttamente Slack con gli eventi Experience Platform.

Problemi comuni

Di seguito sono riportati alcuni problemi che è possibile riscontrare durante la configurazione del proxy e alcuni possibili modi per risolverli.