Slack-Ereignisse in Jitterbit Studio empfangen

Einführung

Die Slack Events API sendet Echtzeit-Benachrichtigungen an eine URL, die Sie in Ihrer Slack-App registrieren (z. B. immer dann, wenn ein Benutzer eine Nachricht in einem Kanal postet). Um diese Ereignisse in Studio zu empfangen, konfigurieren Sie 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 Sie die Endpoint-URL zum ersten Mal in Ihrer Slack-App registrieren, sendet Slack eine Challenge-Anfrage. Der Endpoint muss den Challenge-Wert zurückgeben, bevor Slack Ereignisse sendet.
• 3-Sekunden-Antwortzeitfenster: Slack erwartet HTTP 200 innerhalb von 3 Sekunden nach dem Versenden eines Ereignisses. Operationen, die erhebliche Verarbeitung durchführen, müssen diese Arbeit asynchron auslagern und sofort zurückkehren.

Dieser Leitfaden behandelt die Konfiguration des API-Endpoints, die Verarbeitung der URL-Verifizierung und den Empfang eingehender Ereignisse. Er 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 Ereignis auswählt, welche Operation ausgeführt werden soll, siehe LLM-Antworten mithilfe von Function Calling zu Studio-Operationen leiten.

Dieser Leitfaden setzt Folgendes voraus:

• Eine benutzerdefinierte API ist konfiguriert und in API Manager in der gleichen Umgebung wie das Projekt veröffentlicht.
• Eine Slack-App existiert mit aktivierter Event Subscriptions. Falls nicht vorhanden, erstellen Sie eine App unter api.slack.com/apps und aktivieren Sie Event Subscriptions in den App-Einstellungen.
• Sie sind mit den grundlegenden Schritten zum Erstellen benutzerdefinierter API-Endpoints vertraut.

Teil 1: API-Endpoint erstellen

Schritt 1: API erstellen

1. Öffnen Sie API Manager und klicken Sie auf New API.

2. Wählen Sie Custom API als API-Typ aus.

3. API Name: Geben Sie einen Namen für die API ein (z. B. Slack Event Listener).

4. URL Prefix: Geben Sie ein Basispfad-Segment für die Endpoint-URL ein (z. B. slack).

5. Version: Geben Sie eine Versionsnummer ein (z. B. 1.0).

6. Enable SSL: Aktivieren Sie diese Option. Slack sendet Ereignisse nur an HTTPS-Endpoints.

7. Klicken Sie auf Save.

Schritt 2: Service-Endpoint konfigurieren

1. Klicken Sie im API-Editor auf Add Service.

2. Method: Wählen Sie POST aus.

3. Path: Geben Sie einen Endpoint-Pfad ein (z. B. /events).

4. Operation: Wählen Sie die Studio-Operation aus, die ausgeführt wird, wenn ein Ereignis empfangen wird. Diese Operation enthält das Listener-Skript aus Teil 2 und 3.

5. Response Type: Wählen Sie System Variable aus.

6. Klicken Sie auf Save und dann auf Publish.

Nach der Veröffentlichung kopieren Sie die von API Manager angezeigte Endpoint-URL. Diese URL geben Sie während des Verifizierungsschritts in den Slack-App-Einstellungen ein.

Teil 2: URL-Verifizierung handhaben

Wenn Sie die Endpoint-URL in den Event Subscriptions Einstellungen Ihrer Slack-App eingeben, sendet Slack sofort eine POST-Anfrage, um zu verifizieren, dass die URL Ihnen 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 Antwortkörper zurückgeben.

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

Fügen Sie die folgende Prüfung am Anfang des Listener-Skript-Operation hinzu:

<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-Anfragebody in ein Wörterbuch. Get extrahiert einzelne Felder. Wenn der Typ url_verification ist, erstellt Dict ein Antwortwörterbuch, JSONStringify serialisiert es zu JSON, und Return beendet das Skript, damit 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 Prüfungen sind erforderlich, bevor das Event zur Verarbeitung weitergeleitet wird.

Bot-Nachrichten filtern

Wenn deine Integration Nachrichten an Slack sendet (beispielsweise als Teil eines KI-Agenten oder einer automatisierten Antwort), generieren diese Nachrichten neue Events, die die Operation erneut auslösen. Dies führt zu einer 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 für Nachrichten, die von Bot-Benutzern gesendet werden. Ist das Feld vorhanden, bestätigt das Script 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. Operationen, die ein LLM aufrufen, eine Datenbank abfragen oder mehrere Schritte ausführen, überschreiten dieses Zeitfenster normalerweise.

Führe die Verarbeitungsoperation asynchron mit RunOperation mit runSynchronously auf false gesetzt aus, 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 der Verarbeitungsoperation zu warten. Das Listener-Script setzt die 200-Antwort und beendet sich innerhalb von Millisekunden, was Slacks Timeout erfüllt. Die Verarbeitungsoperation läuft unabhängig im Hintergrund.

Für Überlegungen zu Race Conditions und Concurrency-Limits bei Verwendung asynchroner Operationen siehe Asynchrone Operationen verwalten.

Vollständiges Listener-Script

Das folgende Script kombiniert die URL-Verifizierungsprüfung, den Bot-Filter und die asynchrone Zustellung:

<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 rohe Event-Payload bleibt für nachgelagerte Operationen über $jitterbit.api.request.body verfügbar. Um auf den Benutzer zu antworten oder nach der Verarbeitung eine Nachricht an Slack zu posten, siehe Slack-Benachrichtigung von einer Studio-Operation senden.

Integration verifizieren

1. Stelle das Projekt bereit und bestätige, dass der API-Endpoint im 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 Verified anzeigt. Falls 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 ist.

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 die Listener-Operation ausgeführt wurde und dass die Verarbeitungsoperation weitergeleitet wurde.