Zum Inhalt springen

Webhooks in Jitterbit App Builder

Übersicht

Ein Webhook ist eine automatisierte Benachrichtigung, die zwischen Anwendungen gesendet wird, wenn ein bestimmtes Ereignis eintritt. App Builder nutzt Webhooks, um bestimmte Aktionen als Reaktion auf E-Mails, Textnachrichten oder API-Aufrufe auszulösen.

Eine Anwendung kann beispielsweise eine E-Mail an einen Benutzer senden, um eine Überweisung zu genehmigen oder abzulehnen. Wenn der Benutzer mit „genehmigen" antwortet, löst ein Webhook den Genehmigungsprozess aus. Wenn er mit „ablehnen" antwortet, löst es eine Ablehnung aus. Dies ermöglicht es Benutzern, Aufgaben direkt aus ihrem Postfach oder ihrer Messaging-App zu erledigen, ohne sich wieder in die Hauptanwendung einloggen zu müssen.

Auf dieser Seite wird erklärt, wie man einen Webhook erstellt und konfiguriert:

Diese Seite enthält auch einen Abschnitt zur Fehlerbehebung, der einen häufig auftretenden Webhook-Fehler und dessen Lösung behandelt.

Webhook erstellen

Führe diese Schritte durch, um einen Webhook von Anfang bis Ende einzurichten und freizugeben:

Schritt 1: Webhook-Datenserver hinzufügen

Ein Webhook benötigt seinen eigenen Datenserver vom Typ Webhook API, um eingehende HTTP-Aufrufe zu empfangen. Führe diese Schritte durch, um einen zu erstellen:

  1. Navigiere zur IDE.

  2. Wähle IDE > Datenserver aus.

  3. Klicke auf + Server. Das Dialogfeld Server öffnet sich:

    server dialog

    1. Lege Werte für Folgendes fest:

      • Servername: Gib einen Namen ein.

      • Typ: Wähle Webhook API aus. Dies führt dazu, dass weitere Optionen angezeigt werden.

      • Request Content Type: Wähle JSON aus.

      • Response Content Type: Wähle JSON aus.

    2. Klicke auf Speichern.

    3. Schließe das Dialogfeld.

Mit dem erstellten Server definierst du jetzt den spezifischen Endpunkt, den der Webhook aufruft:

  1. Suche in der Liste der Server nach dem gerade erstellten Server und wähle ihn aus. Dies führt dazu, dass der neue Server im anderen Bereich des Bildschirms aufgelistet wird.

  2. Klicke auf das Symbol Datensatz öffnen:

  3. Das Dialogfeld Webhook API öffnet sich. Klicke im Abschnitt REST API auf Endpunkte:

  4. Die Seite Web Service öffnet sich. Klicke im Bereich Endpunkte auf + Endpunkt:

    Lege Werte für die folgenden Parameter fest:

    • Name: Wähle einen Namen für deinen Endpunkt.

    • Endpunkt: Du kannst dieses Feld leer lassen.

    • Methode: Wähle POST aus.

  5. Klicke auf das Symbol Häkchen, um zu speichern.

Abschließend erkennst du die Parameter, die der Request Body des Webhooks bereitstellt:

  1. Klicke im Bereich Endpunkte auf Entdecken. Das Dialogfeld Endpunkt öffnet sich:

    endpoint dialog

    1. Lege Werte für Folgendes fest:

      • Name: Dieses Feld wird automatisch mit dem Namen gefüllt, den du für den Endpunkt ausgewählt hast.

      • Endpunkt: Du kannst dieses Feld leer lassen.

      • Methode: Wähle POST aus.

      • Request Body: Wenn der Webhook einen Body akzeptiert (z. B. einen POST mit JSON oder XML Request Content Type), stelle einen Beispiel-Request Body bereit. Beispiel:

        {
    "Company": "Jitterbit",
    "Product": "App Builder"
}

    2. Klicke auf Entdecken. App Builder fügt die Endpunkt-Parameter automatisch hinzu.

Schritt 2: Webhook zur Anwendung hinzufügen

Mit dem definierten Webhook-Server und -Endpunkt verknüpfst du diesen Server als Datenquelle in deiner Anwendung:

  1. Gehen Sie zu App Workbench > Datenquellen.

  2. Klicken Sie auf + Quelle. Ein Dialog wird geöffnet.

  3. Wählen Sie Mit vorhandener Quelle verknüpfen.

  4. Klicken Sie auf Weiter.

  5. Suchen Sie die REST-Webhook-API in der Liste, die Sie in Schritt 1 konfiguriert haben, und wählen Sie sie aus.

  6. Klicken Sie auf die Schaltfläche Verknüpfen.

  7. Klicken Sie auf Fertig.

Schritt 3: Eine Webhook-Geschäftsregel erstellen

Erstellen Sie anschließend eine Geschäftsregel, die die eingehenden Daten des Webhooks einer verwendbaren Datenquelle zuordnet:

  1. Gehen Sie zu App Workbench > Datenquellen.

  2. Wählen Sie im Bereich App-Datenquellen die Webhook-Datenquelle aus, die Sie soeben erstellt haben:

  3. Klicken Sie im Bereich Regeln auf + Regel. Der Rule Builder wird geöffnet.

  4. Konfigurieren Sie die neue Regel wie folgt:

    • Name: Geben Sie einen aussagekräftigen Namen für die Regel ein, z. B. WebhookCreation.

    • Zweck: Wählen Sie Webhook. Dies bewirkt, dass weitere Optionen angezeigt werden.

    • Quell-Datenquelle: Wählen Sie die Webhook-Datenquelle aus Schritt 1.

    • Ziel: Wählen Sie den Webhook-Endpunkt aus Schritt 1.

  5. Klicken Sie auf Erstellen. App Builder erstellt die Regel und zeigt ihren Bearbeitungsbildschirm an.

  6. Klicken Sie im Bereich Tabellen auf + Tabellen. Ein Dialog wird geöffnet.

  7. Wählen Sie den Webhook-Endpunkt aus, indem Sie auf die Schaltfläche Hinzufügen klicken. Er wird im Bereich Tabellen angezeigt.

  8. Wählen Sie im Bereich Tabellen alle Spalten des Endpunkts aus.

Schritt 4: Eine XP-CRUD-Geschäftsregel erstellen

Die Webhook-Regel allein definiert nur die Form der eingehenden Daten. Fügen Sie an ihrem Insert-Ereignis eine XP-CRUD-Regel an, damit Daten für andere Regeln und Tabellen in Ihrer Anwendung verfügbar werden:

  1. Klicken Sie im Bearbeitungsbildschirm der Geschäftsregel, die Sie in Schritt 3 erstellt haben, auf Ereignisse im Bereich Regel. Der Dialog Alle Ereignisse wird geöffnet.

  2. Doppelklicken Sie auf die Zeile mit dem Ereignis Insert. Das Fenster Insert wird geöffnet:

  3. Wählen Sie im Bereich Ereignisinformationen im Menü Aktualisierungsbereich die Option Zeilenaktualisierung.

  4. Klicken Sie im Bereich Aktionen auf + Regel & Registrieren. Eine neue Instanz des Rule Builders wird geöffnet. Konfigurieren Sie es wie folgt:

    • Name: Geben Sie einen aussagekräftigen Namen ein, z. B. WebhookCreation_XP_CRUD.

    • Zweck: Wählen Sie XP CRUD.

    • Aktion: Wählen Sie Insert.

    • Ziel-Schicht: Wählen Sie Logik-Schicht.

    • Ziel: Wählen Sie die Geschäftsregel aus, die Sie in Schritt 3 erstellt haben.

  5. Klicken Sie auf Erstellen. Die neue Geschäftsregel wird erstellt und ihr Bearbeitungsbildschirm wird angezeigt.

  6. Klicken Sie im Bereich Tabellen auf + Tabellen.

  7. Wählen Sie den Endpunkt aus, den Sie in Schritt 1 erstellt haben, indem Sie auf die Schaltfläche Hinzufügen klicken. Er wird im Bereich Tabellen angezeigt.

  8. Wählen Sie alle Spalten aus.

  9. Klicken Sie auf Validieren.

Schritt 5: Den Webhook exposieren

Exponieren Sie zum Abschluss die Webhook-Regel über die REST-API von App Builder, damit externe Systeme sie über HTTP aufrufen können:

  1. Wählen Sie IDE > REST-APIs.

  2. Gehen Sie zur Registerkarte Webhooks.

  3. Klicken Sie im Bereich Services auf die Schaltfläche Endpunkte verwalten, um den Dialog Anwendungen zu öffnen:

    Dialog „Anwendungen"

  4. Suchen Sie Ihre Anwendung und klicken Sie auf das Symbol Bleistift.

  5. Geben Sie einen Namen für Ihren Endpunkt ein und klicken Sie auf Fortfahren.

  6. (Seit App Builder 4.67.) Klicken Sie auf das Symbol Authentifizierung für die Anwendung. Der Dialog Authentifizierungsanbieter wird geöffnet. Fügen Sie die API-Schlüssel-, HTTP- oder Authorization-Server-Anbieter hinzu, denen Sie erlauben möchten, Webhook-Anfragen dieser Anwendung zu authentifizieren. Siehe Konfigurieren eines Endpunkts für die genauen Schritte.

    Hinweis

    Diese Option ist bei einer versiegelten Anwendung nicht verfügbar. Bei einer versiegelten Anwendung klicken Sie stattdessen auf das Symbol in ihrer Spalte Web Service auf Anwendungen verwalten, was diesen Dialog Authentifizierungsanbieter von außerhalb der App öffnet.

  7. Schließen Sie den Dialog. Klicken Sie im Services-Bereich auf das Chevron-Symbol auf der Kachel Ihrer Anwendung. Die Webhook API-Seite wird geöffnet und zeigt die Bereiche Service und Webhooks.

  8. (Seit App Builder 4.67.) Klicken Sie im Service-Bereich auf Mehr > Authentifizierung konfigurieren:

    Der Authentication Providers-Dialog aus Schritt 6 wird erneut geöffnet. Fügen Sie Provider hinzu und speichern Sie diese auf die gleiche Weise wie dort beschrieben.

  9. Klicken Sie im Webhooks-Bereich auf + Webhook. Der Webhook-Dialog wird geöffnet:

    Webhook-Dialog

    Konfigurieren Sie ihn wie folgt:

    • Webhook: Wählen Sie die Webhook-Regel aus, die Sie erstellt haben. Nach dem Speichern des Dialogs wird das Symbol neben diesem Feld anklickbar und leitet Sie zur Rule Builder-Seite der Regel in der App Workbench weiter.

    • Endpoint: Geben Sie den Pfadsegment ein, unter dem auf den Webhook zugegriffen wird.

    • Compatibility: Behalten Sie die Standardoption bei. Weitere Informationen zu verfügbaren Optionen, die auch hier gelten, finden Sie unter Compatibility.

  10. Klicken Sie auf Save.

  11. (Optional.) Klicken Sie auf das Symbol Details des Webhooks, um den Webhook-Dialog zu öffnen. Dort können Sie Request/Response-Plug-ins konfigurieren, die die Payload beim Durchlaufen des Webhooks transformieren.

Schritt 6: Erstellen Sie einen API-Schlüssel für einen Benutzer

Generieren Sie abschließend einen API-Schlüssel, damit ein bestimmter Benutzer Aufrufe an diesen Webhook authentifizieren kann:

  1. Wählen Sie IDE > User Management.

  2. Wählen Sie im Users-Bereich einen Benutzer mit Administratorrechten aus und doppelklicken Sie auf seine Zeile. Der User-Dialog wird geöffnet:

    Benutzer-Dialog

  3. Klicken Sie auf Mehr > Keys. Der Keys-Dialog wird geöffnet.

  4. Klicken Sie auf Create. Der Generate Key-Dialog wird geöffnet.

  5. Konfigurieren Sie den neuen Schlüssel wie folgt:

    • Provider: Wählen Sie Ihren API Key-Sicherheitsanbieter aus (siehe Richten Sie einen Sicherheitsanbieter für API-Schlüssel ein, falls Sie noch keinen konfiguriert haben).

    • Description: (Optional) Geben Sie eine kurze Beschreibung ein.

    • Expires In: (Optional) Geben Sie eine benutzerdefinierte Ablaufzeit ein.

  6. Klicken Sie auf Save, um den API-Schlüssel zu erstellen.

Wichtig

Notieren Sie sich die Informationen, da sie nicht erneut angezeigt werden können.

Benutzer-Dialog

Schritt 7: Testen Sie den Webhook

Sie sollten Ihren neuen Webhook testen (z. B. mit Postman, Insomnia oder ähnlichen Tools). Senden Sie einen POST-API-Aufruf mit einem Body, der dem in Schritt 1 verwendeten Body ähnelt. Verwenden Sie die Standardauthentifizierung mit der Kennung und dem Schlüssel aus Schritt 6 als Benutzername und Passwort.

Verwenden Sie zum Testen den Link: https://<url>/webhook/v1/<application-endpoint>/<endpoint>.

Wenn keine Authentifizierung erforderlich ist, können Sie die URL statt der Konfiguration eines x-api-key in der Kopfzeile auf eine der folgenden Optionen anpassen:

  1. https://{{user's identifier from Step 6}}:{{user's key from Step 6}}@{{url from Step 7}} (wird verwendet, wenn der Anbieter HTTP Basic Auth ohne Parameter ist)

    Vorsicht

    Die oben beschriebene HTTP Basic-Methode erfordert, dass die Authorization-Kopfzeile in der empfangenen Payload enthalten ist. Um dies zu umgehen, verwenden Sie stattdessen die API Key-Methode.

  2. https://{{url from step7}}?apiKey={{user's key from Step 6}} (wird verwendet, wenn der Anbieter API Key ist und die Properties den HttpHeaderName 'X-API-Key' enthalten)

Fehlerbehebung

Eine häufige Ursache für Fehler bei der Webhook-Authentifizierung finden Sie unter Webhook: HTTP Basic Auth erfordert den Authorization-Header in der Payload im App Builder Troubleshooting-Leitfaden.