Überwachen von Experience Platform-Ereignissen in Slack

Erfahren Sie, wie Sie Experience Platform-Benachrichtigungen in Slack erhalten, indem Sie sie mit einem Adobe App Builder-Webhook-Proxy integrieren. Dateningenieure und Administratoren möchten möglicherweise proaktive Benachrichtigungen in Slack von Adobe Experience Platform erhalten, um den Zustand ihrer Platform-Implementierungen zu überwachen. In diesem Tutorial werden die Architektur und Implementierungsschritte zum Verbinden von Adobe I/O Events mit Slack mithilfe von Adobe App Builder beschrieben.

Warum ein Webhook-Proxy?

Das direkte Verbinden von Adobe I/O Events mit einem eingehenden Slack-Webhook ist aufgrund einer Protokollabweichung im Verifizierungsprozess nicht möglich.

Überblick über die Architektur

Was ist Adobe Developer Console?

Adobe Developer Console ist das zentrale Portal zur Verwaltung Ihrer Adobe-Projekte, APIs und Berechtigungen. Hier erstellen Sie Ihr Projekt, konfigurieren die Authentifizierung und registrieren Ihre Webhooks.

Was ist App Builder?

Adobe App Builder ist ein vollständiges Framework, mit dem Unternehmensentwickler Cloud-native Programme erstellen können.

Was ist Adobe I/O Runtime?

Adobe I/O Runtime ist die Server-lose Plattform für App Builder. Dadurch können Entwickler Code (Functions-as-a-Service) bereitstellen, der als Reaktion auf HTTP-Anfragen ausgeführt wird, ohne die Server-Infrastruktur zu verwalten.

In dieser Implementierung verwenden wir eine Aktion. Eine Aktion ist eine statuslose Funktion (geschrieben in Node.js), die auf der Adobe I/O Runtime ausgeführt wird. Unsere Aktion dient als öffentlicher HTTP-Endpunkt, mit dem Adobe I/O Events kommuniziert.

Weitere Informationen finden Sie in der Dokumentation zu Adobe I/O Runtime.

Implementierungshandbuch

Voraussetzungen

Bevor Sie beginnen, stellen Sie Folgendes sicher:

Schritt 1: Erstellen eines Projekts in Adobe Developer Console

Erstellen Sie zunächst ein Projekt mit der App Builder-Vorlage in Adobe Developer Console:

Initialisieren der Laufzeitumgebung

Führen Sie die folgenden Befehle in Ihrem Terminal aus, um die Projektstruktur zu erstellen:

Anmelden bei aio

aio login

Schritt 2: Initialisieren eines neuen App Builder-Projekts

aio app init slack-webhook-proxy

Die App-Initialisierung sollte abgeschlossen sein.

Navigieren Sie zum Projektverzeichnis

cd slack-webhook-proxy

Hinzufügen der Web-Aktion

aio app add action

Schritt 3: Proxy-Aktionscode aktualisieren

Erstellen/ändern Sie in einer IDE oder einem Texteditor den actions/webhook-proxy/index.js mit folgendem Code. Diese Implementierung leitet Ereignisse an Slack weiter. Die Signaturüberprüfung und die Verarbeitung von Challenges erfolgen bei Verwendung der Laufzeitaktionsregistrierung automatisch.

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;

Schritt 4: Konfigurieren der Aktion

Die Aktionskonfiguration in app.config.yaml ist wichtig. Web verwenden: Nein, um eine Nicht-Web-Aktion zu erstellen, die als Laufzeitaktion in der Developer Console registriert werden kann.

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

Warum web: no?

Wenn Sie eine Nicht-Web-Aktion verwenden und diese über die Option „Laufzeitaktion“ in der Developer Console registrieren, wird Adobe I/O Events automatisch wie folgt konfiguriert:

Das bedeutet, dass Ihr Code nur die Geschäftslogik (Weiterleitung an Slack) verarbeiten muss.

Schritt 4: Aktualisieren der Umgebungsvariablen

Um Anmeldeinformationen sicher zu verwalten, verwenden wir Umgebungsvariablen. Erstellen/ändern Sie die .env-Datei im Stammverzeichnis Ihres Projekts, um Ihre Slack-Webhook-URL hinzuzufügen. Stellen Sie sicher, dass auf Ihrem System ausgeblendete Dateien angezeigt werden, wenn die .env nicht angezeigt wird:

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

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

Schritt 5: Bereitstellen der Aktion

Stellen Sie nach dem Festlegen der Umgebungsvariablen die Aktion bereit. Stellen Sie sicher, dass Sie sich im Stammverzeichnis Ihres Projekts befinden, d. h. slack-webhook-proxy, wenn Sie diesen Befehl im Terminal ausführen.

aio app deploy

Ihre Aktion wird in Adobe I/O Runtime bereitgestellt und steht in der Developer Console zur Registrierung zur Verfügung.

Schritt 6: Aktion in Adobe Developer Console registrieren

Nachdem Ihre Aktion bereitgestellt wurde, registrieren Sie sie als Ziel für Adobe Events.

Schritt 7: Mit einem Beispielereignis validieren

Sie können den gesamten Fluss End-to-End testen, indem Sie auf das Symbol „Beispielereignis senden“ neben einem konfigurierten Ereignis klicken.

Das Beispielereignis wird über den Kanal gesendet, den Sie beim Erstellen Ihrer Slack-App und des Webhooks konfiguriert haben. Es sollte etwas Ähnliches wie das folgende angezeigt werden:

Herzlichen Glückwunsch, Sie haben Slack erfolgreich in Experience Platform Events integriert!

Häufige Probleme

Im Folgenden finden Sie einige Probleme, auf die Sie bei der Konfiguration des Proxys stoßen können, sowie einige potenzielle Möglichkeiten, diese zu beheben.