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 spezifische Aktionen als Reaktion auf E-Mails, Textnachrichten oder API-Aufrufe auszulösen.

Beispielsweise könnte eine Anwendung einem Benutzer eine E-Mail senden, um eine Überweisung zu genehmigen oder abzulehnen. Antwortet der Benutzer mit „genehmigen", löst ein Webhook den Genehmigungsprozess aus; antwortet er mit „ablehnen", wird die Ablehnung ausgelöst. Dies ermöglicht es Benutzern, Aufgaben direkt aus ihrem Posteingang oder ihrer Messaging-App zu erledigen, ohne sich erneut in der Hauptanwendung anmelden zu müssen.

Diese Seite führt Sie durch die Schritte zum Erstellen und Konfigurieren eines Webhooks:

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

Einen Webhook erstellen

Führen Sie diese Schritte aus, um einen Webhook von Anfang bis Ende einzurichten und freizugeben:

Schritt 1: Einen Webhook-Datenserver hinzufügen

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

  1. Navigieren Sie zur IDE.

  2. Wählen Sie IDE > Datenserver.

  3. Klicken Sie auf + Server. Das Dialogfeld Server wird geöffnet:

    server dialog

    1. Legen Sie Werte für Folgendes fest:

      • Servername: Geben Sie einen Namen ein.

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

      • Request Content Type: Wählen Sie JSON.

      • Response Content Type: Wählen Sie JSON.

    2. Klicken Sie auf Speichern.

    3. Schließen Sie das Dialogfeld.

Nachdem der Server erstellt wurde, definieren Sie den spezifischen Endpunkt, den der Webhook aufruft:

  1. Suchen Sie in der Serverliste den gerade erstellten Server und wählen Sie ihn aus. Dadurch wird der neue Server im anderen Bereich des Bildschirms aufgelistet.

  2. Klicken Sie auf das Symbol Datensatz öffnen:

    open record

  3. Das Dialogfeld Webhook API wird geöffnet. Klicken Sie im Abschnitt REST API auf Endpunkte:

    webhook API dialog

  4. Die Seite Web Service wird geöffnet. Klicken Sie im Bereich Endpunkte auf + Endpunkt:

    web service page

    Legen Sie Werte für die folgenden Parameter fest:

    • Name: Wählen Sie einen Namen für Ihren Endpunkt.

    • Endpunkt: Sie können dieses Feld leer lassen.

    • Methode: Wählen Sie POST.

  5. Klicken Sie auf das Symbol Häkchen zum Speichern.

Entdecken Sie abschließend die Parameter, die der Request Body des Webhooks bereitstellt:

  1. Klicken Sie im Bereich Endpunkte auf Entdecken. Das Dialogfeld Endpunkt wird geöffnet:

    endpoint dialog

    1. Legen Sie Werte für Folgendes fest:

      • Name: Dieses Feld wird automatisch mit dem Namen gefüllt, den Sie für den Endpunkt gewählt haben.

      • Endpunkt: Sie können dieses Feld leer lassen.

      • Methode: Wählen Sie POST.

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

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

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

Schritt 2: Den Webhook zur Anwendung hinzufügen

Nachdem der Webhook-Server und der Endpunkt definiert sind, verknüpfen Sie diesen Server als Datenquelle in Ihrer 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 auf, die Sie in Schritt 1 konfiguriert haben, und wählen Sie sie in der Liste aus.

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

  7. Klicken Sie auf Fertig.

Schritt 3: Erstellen einer Webhook-Geschäftsregel

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 gerade erstellt haben:

    Regel erstellen

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

  4. Konfigurieren Sie Ihre 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 führt dazu, dass weitere Optionen angezeigt werden.

    • Quelldatenquelle: 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 aus dem Endpunkt aus.

Schritt 4: Erstellen einer XP CRUD-Geschäftsregel

Die Webhook-Regel allein definiert nur die Form der eingehenden Daten. Fügen Sie eine XP CRUD-Regel an sein Insert-Ereignis 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, im Bereich Regel auf Ereignisse. Der Dialog Alle Ereignisse wird geöffnet.

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

    Insert-Fenster

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

  4. Klicken Sie im Bereich Aktionen auf + Regel & Registrieren. Eine neue Instanz des Rule Builder wird geöffnet. Konfigurieren Sie sie 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.

    • Zielschicht: Wählen Sie Logic Layer.

    • 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 seine Spalten aus.

  9. Klicken Sie auf Validieren.

Schritt 5: Webhook verfügbar machen

Machen Sie abschließend die Webhook-Regel über die REST-API von App Builder verfügbar, 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 Stift.

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

  6. (Ab 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, die Sie zur Authentifizierung der Webhook-Anfragen dieser Anwendung zulassen möchten. Siehe Endpunkt konfigurieren für die genauen Schritte.

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

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

    Menü „Mehr", Schaltfläche „Authentifizierung konfigurieren"

    Das gleiche Dialog Authentifizierungsanbieter aus Schritt 6 wird geöffnet. Fügen Sie Anbieter auf die gleiche Weise hinzu und speichern Sie sie wie dort beschrieben.

  9. Klicken Sie im Panel Webhooks auf + Webhook. Das Dialog Webhook wird geöffnet:

    Webhook-Dialog

    Konfigurieren Sie es wie folgt:

    • Webhook: Wählen Sie die Webhook-Regel aus, die Sie erstellt haben. Nachdem das Dialog gespeichert wurde, wird das Symbol neben diesem Feld anklickbar und führt Sie zur Seite Rule Builder der Regel in der App Workbench.

    • Endpoint: Geben Sie das Pfadsegment ein, über das auf den Webhook zugegriffen wird.

    • Kompatibilität: Behalten Sie die Standardoption bei. Unter Kompatibilität finden Sie die verfügbaren Optionen, die hier ebenfalls gelten.

  10. Klicken Sie auf Speichern.

  11. (Optional.) Klicken Sie auf das Symbol Details des Webhooks, um das Dialog Webhook anzuzeigen, in dem Sie Request/Response-Plugins konfigurieren können, die die Payload beim Durchlaufen des Webhooks transformieren.

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

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

  1. Wählen Sie IDE > Benutzerverwaltung.

  2. Wählen Sie im Panel Benutzer einen Benutzer mit Administratorrechten aus und doppelklicken Sie auf seine Zeile. Das Dialog Benutzer wird geöffnet:

    Benutzerdialog

  3. Klicken Sie auf Mehr > Schlüssel. Das Dialog Schlüssel wird geöffnet.

  4. Klicken Sie auf Erstellen. Das Dialog Schlüssel generieren wird geöffnet.

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

    • Anbieter: Wählen Sie Ihren API-Schlüssel-Sicherheitsanbieter aus (siehe Sicherheitsanbieter für API-Schlüssel einrichten, wenn Sie noch keinen konfiguriert haben).

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

    • Verfällt in: (Optional) Geben Sie eine benutzerdefinierte Ablaufzeit ein.

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

Wichtig

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

Benutzerdialog

Schritt 7: Webhook testen

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

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 im Header auf eine der folgenden Optionen anpassen:

  1. https://{{Kennung des Benutzers aus Schritt 6}}:{{Schlüssel des Benutzers aus Schritt 6}}@{{URL aus Schritt 7}} (zu verwenden, wenn der Anbieter HTTP-Standardauthentifizierung ohne Parameter ist)

    Vorsicht

    Die oben beschriebene HTTP-Standardmethode erfordert, dass der Authorization-Header in der empfangenen Payload enthalten ist. Um dies zu umgehen, verwenden Sie stattdessen die API-Schlüssel-Methode.

  2. https://{{URL aus Schritt 7}}?apiKey={{Schlüssel des Benutzers aus Schritt 6}} (zu verwenden, wenn der Anbieter API-Schlüssel ist und die Eigenschaften den HttpHeaderName „X-API-Key" enthalten)

Fehlerbehebung

Eine häufige Ursache für Webhook-Authentifizierungsfehler finden Sie unter Webhook: HTTP-Standardauthentifizierung erfordert den Authorization-Header in der Payload im App-Builder-Fehlerbehebungsleitfaden.