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", löst es eine Ablehnung aus. So können Benutzer Aufgaben direkt aus ihrem Posteingang oder ihrer Messaging-App heraus erledigen, ohne sich wieder in der Hauptanwendung anmelden zu müssen.

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

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

Einen Webhook erstellen

Führe diese Schritte aus, um einen Webhook von Anfang bis Ende zu konfigurieren 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ühre diese Schritte aus, um einen zu erstellen:

  1. Navigiere zur IDE.

  2. Wähle IDE > Datenserver aus.

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

    Server-Dialogfeld

    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-Typ: Wähle JSON aus.

      • Response-Content-Typ: Wähle JSON aus.

    2. Klicke auf Speichern.

    3. Schließe das Dialogfeld.

Nachdem du den Server erstellt hast, definiere den spezifischen Endpunkt, den der Webhook aufruft:

  1. Suche in der Liste der Server den soeben erstellten Server und wähle ihn aus. Der Server wird daraufhin in dem anderen Bereich auf dem Bildschirm aufgelistet.

  2. Klicke auf das Symbol Datensatz öffnen:

    Datensatz öffnen

  3. Das Dialogfeld Webhook API wird geöffnet. Klicke im Bereich REST API auf Endpunkte:

    Webhook API-Dialogfeld

  4. Die Seite Webdienst wird geöffnet. Klicke im Bereich Endpunkte auf + Endpunkt:

    Webdienst-Seite

    Lege Werte für die folgenden Parameter fest:

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

    • Endpunkt: Du kannst dieses Feld leer lassen.

    • Methode: Wähle POST aus.

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

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

  1. Klicke im Bereich Endpunkte auf Ermitteln. Das Dialogfeld Endpunkt wird geöffnet:

    Endpunkt-Dialogfeld

    1. Lege Werte für Folgendes fest:

      • Name: Dieses Feld wird automatisch mit dem Namen gefüllt, den du für den Endpunkt gewä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-Typ), gib einen Beispiel-Request-Body an. Beispiel:

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

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

Schritt 2: Den Webhook zu deiner Anwendung hinzufügen

Nachdem du den Webhook-Server und den Endpunkt definiert hast, verbinde diesen Server als Datenquelle in deiner Anwendung:

  1. Gehe zu App Workbench > Datenquellen.

  2. Klicke auf + Quelle. Ein Dialog wird geöffnet.

  3. Wähle Mit vorhandener Quelle verknüpfen.

  4. Klicke auf Weiter.

  5. Suche in der Liste die REST-Webhook-API, die du in Schritt 1 konfiguriert hast, und wähle sie aus.

  6. Klicke auf die Schaltfläche Verknüpfen.

  7. Klicke auf Fertig.

Schritt 3: Eine Webhook-Geschäftsregel erstellen

Erstelle dann eine Geschäftsregel, die die eingehenden Daten des Webhooks einer nutzbaren Datenquelle zuordnet:

  1. Gehe zu App Workbench > Datenquellen.

  2. Wähle im Bereich App-Datenquellen die Webhook-Datenquelle aus, die du gerade erstellt hast:

    eine Regel erstellen

  3. Klicke im Bereich Regeln auf + Regel. Der Regel-Builder wird geöffnet.

  4. Konfiguriere deine neue Regel wie folgt:

    • Name: Gib einen aussagekräftigen Namen für die Regel ein, beispielsweise WebhookCreation.

    • Zweck: Wähle Webhook. Dadurch werden weitere Optionen angezeigt.

    • Quelldatenquelle: Wähle die Webhook-Datenquelle aus Schritt 1.

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

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

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

  7. Wähle den Webhook-Endpunkt aus, indem du auf seine Schaltfläche Hinzufügen klickst. Er wird im Bereich Tabellen angezeigt.

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

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

Die alleinige Webhook-Regel definiert nur die Form der eingehenden Daten. Füge eine XP-CRUD-Regel an sein Insert-Ereignis an, damit Daten für andere Regeln und Tabellen in deiner Anwendung verfügbar werden:

  1. Im Bearbeitungsbildschirm der Geschäftsregel, die du in Schritt 3 erstellt hast, klicke auf Ereignisse im Bereich Regel. Der Dialog Alle Ereignisse wird geöffnet.

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

    insert-fenster

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

  4. Klicke im Bereich Aktionen auf + Regel & Registrieren. Eine neue Instanz des Regel-Builders wird geöffnet. Konfiguriere sie wie folgt:

    • Name: Gib einen aussagekräftigen Namen ein, beispielsweise WebhookCreation_XP_CRUD.

    • Zweck: Wähle XP CRUD.

    • Aktion: Wähle Insert.

    • Zielschicht: Wähle Logic Layer.

    • Ziel: Wähle die Geschäftsregel aus, die du in Schritt 3 erstellt hast.

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

  6. Klicke im Bereich Tabellen auf + Tabellen.

  7. Wähle den Endpunkt aus, den du in Schritt 1 erstellt hast, indem du auf seine Schaltfläche Hinzufügen klickst. Er wird im Bereich Tabellen angezeigt.

  8. Wähle alle seine Spalten aus.

  9. Klicke auf Validieren.

Schritt 5: Den Webhook freigeben

Zum Abschluss gib die Webhook-Regel über die REST-API von App Builder frei, damit externe Systeme sie über HTTP aufrufen können:

  1. Wähle IDE > REST-APIs.

  2. Gehe zur Registerkarte Webhooks.

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

    Dialogfeld „Anwendungen"

  4. Suche deine Anwendung und klicke auf sein Stiftsymbol.

  5. Gib einen Namen für deinen Endpunkt ein und klicke dann auf Fortfahren.

  6. (Ab App Builder 4.67.) Klicke auf das Symbol Authentifizierung für die Anwendung. Der Dialog Authentifizierungsanbieter wird geöffnet. Füge die API-Schlüssel-, HTTP- oder Authorization-Server-Anbieter hinzu, die du dieser Webhook-Anfrage der Anwendung erlauben möchtest. Siehe Einen Endpunkt konfigurieren für die genauen Schritte.

    Hinweis

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

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

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

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

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

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

    Webhook-Dialog

    Konfigurieren Sie ihn wie folgt:

    • Webhook: Wählen Sie die Webhook-Regel aus, die Sie erstellt haben. Nachdem der Dialog gespeichert ist, 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 den Dialog Webhook anzuzeigen. Darin können Sie Request/Response-Plugins konfigurieren, die die Payload während der Übertragung durch den Webhook 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 Bereich Benutzer einen Benutzer mit Administratorrechten aus und doppelklicken Sie auf seine Zeile. Der Dialog Benutzer wird geöffnet:

    Benutzerdialog

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

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

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

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

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

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

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

Wichtig

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

Benutzerdialog

Schritt 7: Webhook testen

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

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

Wenn keine Authentifizierung erforderlich ist, können Sie die URL statt einer 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 Provider HTTP-Basisauthentifizierung ohne Parameter ist)

    Vorsicht

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

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

Fehlerbehebung

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