Slack-Events in Jitterbit Studio empfangen

Einführung

Die Slack Events API liefert Echtzeit-Benachrichtigungen an eine URL, die man in der Slack-App registriert (beispielsweise immer dann, wenn ein Benutzer eine Nachricht in einem Kanal postet). Um diese Events in Studio zu empfangen, konfiguriert man einen API Manager-Endpoint, der die eingehenden POST-Anfragen akzeptiert.

Die Slack Events API hat zwei Anforderungen, die sich von einem Standard-Webhook unterscheiden:

• URL-Verifizierung: Wenn man die Endpoint-URL zum ersten Mal in der Slack-App registriert, sendet Slack eine Challenge-Anfrage. Der Endpoint muss den Challenge-Wert zurückgeben, bevor Slack Events liefert.
• 3-Sekunden-Antwortzeitfenster: Slack erwartet HTTP 200 innerhalb von 3 Sekunden nach dem Versenden eines Events. Operationen, die umfangreiche Verarbeitung durchführen, müssen diese Arbeit asynchron auslagern und sofort zurückkehren.

Diese Anleitung behandelt die Konfiguration des API-Endpoints, die Handhabung der URL-Verifizierung und den Empfang eingehender Events. Sie endet an dem Punkt, an dem die Event-Payload empfangen und zur Verarbeitung weitergeleitet wird. Um die Payload zu nachgelagerten Operationen zu leiten, siehe Operationen verketten und steuern. Für KI-Agent-Anwendungsfälle, bei denen ein LLM basierend auf dem Event auswählt, welche Operation ausgeführt wird, siehe LLM-Antworten mithilfe von Function Calling zu Studio-Operationen leiten.

Diese Anleitung setzt Folgendes voraus:

• Eine benutzerdefinierte API ist in API Manager in derselben Umgebung wie das Projekt konfiguriert und veröffentlicht.
• Eine Slack-App existiert mit aktivierten Event Subscriptions. Falls nicht vorhanden, erstelle eine App unter api.slack.com/apps und aktiviere Event Subscriptions in den App-Einstellungen.
• Man ist mit den grundlegenden Schritten zum Erstellen benutzerdefinierter API-Endpoints vertraut.

Teil 1: API-Endpoint erstellen

Schritt 1: API erstellen

1. Öffne API Manager und klicke auf New API.

2. Wähle Custom API als API-Typ.

3. API Name: Gib einen Namen für die API ein (beispielsweise Slack Event Listener).

4. URL Prefix: Gib ein Basispfad-Segment für die Endpoint-URL ein (beispielsweise slack).

5. Version: Gib eine Versionsnummer ein (beispielsweise 1.0).

6. Enable SSL: Aktiviere diese Option. Slack liefert Events nur an HTTPS-Endpoints.

7. Klicke auf Save.

Schritt 2: Service-Endpoint konfigurieren

1. Klicke im API-Editor auf Add Service.

2. Method: Wähle POST.

3. Path: Gib einen Endpoint-Pfad ein (beispielsweise /events).

4. Operation: Wähle die Studio-Operation aus, die ausgeführt wird, wenn ein Event empfangen wird. Diese Operation enthält das in den Teilen 2 und 3 beschriebene Listener-Skript.

5. Response Type: Wähle System Variable.

6. Klicke auf Save und dann auf Publish.

Nach der Veröffentlichung kopiere die von API Manager angezeigte Endpoint-URL. Diese URL wirst du während des Verifizierungsschritts in den Slack-App-Einstellungen eingeben.

Teil 2: URL-Verifizierung handhaben

Wenn man die Endpoint-URL in den Event Subscriptions-Einstellungen der Slack-App eingibt, sendet Slack sofort eine POST-Anfrage, um zu verifizieren, dass die URL dir gehört. Der Anfragebody enthält ein type-Feld mit dem Wert url_verification und ein challenge-Feld mit einem zufälligen Token. Der Endpoint muss diesen Token im Response-Body zurückgeben.

Wenn der Endpoint nicht korrekt antwortet, lehnt Slack die URL ab und Event Subscriptions können nicht aktiviert werden.

Füge die folgende Prüfung am Anfang des Listener-Skript-Operation ein:

<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 analysiert den Raw-Request-Body in ein Dictionary. Get extrahiert einzelne Felder. Wenn der Typ url_verification ist, erstellt Dict ein Response-Dictionary, JSONStringify serialisiert es zu JSON, und Return beendet das Skript, sodass keine Event-Verarbeitungslogik für diese Anfrage ausgeführt wird.

Teil 3: Event-Nachrichten empfangen

Nach Abschluss der URL-Verifizierung sendet Slack Event-Payloads für alle Aktivitäten, die den Event-Typen entsprechen, die du abonniert hast. Zwei zusätzliche Überprüfungen sind erforderlich, bevor das Event zur Verarbeitung weitergeleitet wird.

Bot-Nachrichten filtern

Wenn deine Integration Nachrichten zurück an Slack sendet (beispielsweise als Teil eines KI-Agenten oder einer automatisierten Antwort), generieren diese Nachrichten neue Events, die den Vorgang erneut auslösen. Dies erzeugt eine Endlosschleife. Filtere Bot-Nachrichten vor der Verarbeitung:

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

Slack setzt event.bot_id bei Nachrichten, die von Bot-Benutzern gesendet werden. Wenn das Feld vorhanden ist, bestätigt das Skript das Event mit HTTP 200 und beendet sich, ohne es zu verarbeiten.

Verarbeitung asynchron ausführen

Slack bricht die Event-Zustellung ab und versucht erneut, wenn der Endpoint nicht innerhalb von 3 Sekunden antwortet. Vorgänge, die ein LLM aufrufen, eine Datenbank abfragen oder mehrere Schritte ausführen, überschreiten dieses Zeitfenster normalerweise.

Führe den Verarbeitungsvorgang asynchron mit RunOperation aus, wobei runSynchronously auf false gesetzt ist, und stelle dann sofort die Antwort bereit:

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

Der Parameter false teilt Studio mit, nicht auf den Abschluss des Verarbeitungsvorgangs zu warten. Das Listener-Skript setzt die 200-Antwort und beendet sich innerhalb von Millisekunden, was Slacks Timeout erfüllt. Der Verarbeitungsvorgang läuft unabhängig im Hintergrund.

Überlegungen zu Race Conditions und Concurrency Limits bei der Verwendung asynchroner Vorgänge findest du unter Manage asynchronous operations.

Vollständiges Listener-Skript

Das folgende Skript kombiniert die URL-Verifizierungsprüfung, den Bot-Filter und den asynchronen Dispatch:

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

Die Raw Event-Payload bleibt für nachgelagerte Vorgänge über $jitterbit.api.request.body verfügbar. Um nach der Verarbeitung auf den Benutzer zu antworten oder eine Nachricht zurück an Slack zu senden, siehe Send a Slack notification from a Studio operation.

Integration verifizieren

1. Stelle das Projekt bereit und bestätige, dass der API-Endpoint in API Manager veröffentlicht ist.

2. Gehe in deinen Slack-App-Einstellungen zu Event Subscriptions und füge die Endpoint-URL in das Feld Request URL ein. Slack sendet die URL-Verifizierungsanfrage automatisch.

3. Bestätige, dass das Feld Request URL den Status Verified anzeigt. Wenn die Verifizierung fehlschlägt, öffne die operation logs in Studio, um auf Fehler zu prüfen, und bestätige, dass die Endpoint-URL korrekt ist und das Projekt bereitgestellt wurde.

4. Füge unter Subscribe to Bot Events die Event-Typen hinzu, die du empfangen möchtest (beispielsweise message.channels oder app_mention). Klicke auf Save Changes.

5. Installiere die App erneut in deinem Workspace, wenn Slack dich dazu auffordert.

6. Poste eine Nachricht in einem Slack-Channel, in dem der Bot Mitglied ist.

7. Öffne die operation logs in Studio und bestätige, dass der Listener-Vorgang ausgeführt wurde und der Verarbeitungsvorgang weitergeleitet wurde.