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

Webhook erstellen

Hier ist eine Zusammenfassung der erforderlichen Schritte zum Erstellen eines Webhooks:

Schritt 1: Webhook in Datenservern hinzufügen

Gehen Sie wie folgt vor, um einen Server einzurichten:

  1. Navigieren Sie zur IDE.

  2. Wählen Sie IDE > Data Servers aus.

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

    server dialog

    1. Legen Sie Werte für Folgendes fest:

      • Server Name: Geben Sie einen Namen ein.

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

      • Request Content Type: Wählen Sie JSON aus.

      • Response Content Type: Wählen Sie JSON aus.

    2. Klicken Sie auf Save.

    3. Schließen Sie das Dialogfeld.

Gehen Sie wie folgt vor, um einen Endpunkt zu erstellen:

  1. Suchen Sie in der Liste der Server 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 Open record:

    open record

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

    webhook api popup

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

    web service page

    Legen Sie Werte für die folgenden Parameter fest:

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

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

    • Method: Wählen Sie POST aus.

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

Gehen Sie wie folgt vor, um Parameter für Ihren Endpunkt zu erstellen:

  1. Klicken Sie im Bereich Endpoints auf Discover. Das Dialogfeld Endpoint 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.

      • End Point: Sie können dieses Feld leer lassen.

      • Method: Wählen Sie POST aus.

      • Request Body: Wenn der Webhook einen Body akzeptiert (z. B. einen 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 Discover. App Builder fügt die Endpunkt-Parameter automatisch hinzu.

Schritt 2: Webhook zur Anwendung hinzufügen

Gehen Sie wie folgt vor, um den Webhook zu Ihrer Anwendung hinzuzufügen:

  1. Gehen Sie zu App Workbench > Data Sources.

  2. Klicken Sie auf + Source. Ein Dialogfeld wird geöffnet.

  3. Wählen Sie Link to existing source aus.

  4. Klicken Sie auf Next.

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

  6. Klicken Sie auf die Schaltfläche Link.

  7. Klicken Sie auf Done.

Schritt 3: Webhook-Geschäftsregel erstellen

Um eine Geschäftsregel zu erstellen, führen Sie diese Schritte aus:

  1. Gehen Sie zu App Workbench > Data Sources.

  2. Wählen Sie im Panel App Data Sources die Webhook-Datenquelle aus, die Sie gerade erstellt haben:

    create a rule

  3. Klicken Sie im Panel Rules auf + Rule. 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.

    • Purpose: Wählen Sie Webhook. Dadurch werden weitere Optionen angezeigt.

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

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

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

  6. Klicken Sie im Panel Tables auf + Tables. Ein Dialog wird geöffnet.

  7. Wählen Sie den Webhook-Endpunkt aus, indem Sie auf die Schaltfläche Add klicken. Er wird im Panel Tables angezeigt.

  8. Wählen Sie im Panel Tables alle Spalten aus dem Endpunkt aus.

Schritt 4: XP CRUD-Geschäftsregel erstellen

Um eine XP CRUD-Geschäftsregel zu erstellen, führen Sie diese Schritte aus:

  1. Klicken Sie im Bearbeitungsbildschirm der Geschäftsregel, die Sie in Schritt 3 erstellt haben, im Panel Rule auf Events. Der Dialog All Events wird geöffnet.

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

    insert window

  3. Wählen Sie im Panel Event Information im Menü Refresh Scope die Option Row Refresh aus.

  4. Klicken Sie im Panel Actions auf + Rule & Register. 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.

    • Purpose: Wählen Sie XP CRUD.

    • Action: Wählen Sie Insert.

    • Target Layer: Wählen Sie Logic Layer.

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

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

  6. Klicken Sie im Panel Tables auf + Tables.

  7. Wählen Sie den Endpunkt aus, den Sie in Schritt 1 erstellt haben, indem Sie auf die Schaltfläche Add klicken. Er wird im Panel Tables angezeigt.

  8. Wählen Sie alle seine Spalten aus.

  9. Klicken Sie auf Validate.

Schritt 5: Webhook verfügbar machen

Um einen Endpunkt für Ihre Anwendung zu erstellen, führen Sie diese Schritte aus:

  1. Wählen Sie IDE > REST APIs.

  2. Gehen Sie zur Registerkarte Webhooks.

  3. Klicken Sie im Panel Application auf die Schaltfläche Manage Endpoints, um den Dialog Application Endpoints zu öffnen:

    manage endpoints

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

  6. Schließen Sie den Dialog. Ihre Anwendung wird zusammen mit den anderen im Panel Application aufgelistet. Klicken Sie einmal auf die Kachel, um sie auszuwählen.

  7. Klicken Sie im Panel Webhooks auf + Webhook. Der Dialog Webhook wird geöffnet:

    webhook dialog

    Konfigurieren Sie ihn wie folgt:

    • Webhook: Wählen Sie den Webhook aus, den Sie erstellt haben.

    • Endpoint: Geben Sie einen aussagekräftigen Namen ein.

    • Compatibility: Behalten Sie die Standardoption bei.

      Hinweis

      Seit App Builder 4.51 bietet das Feld Compatibility diese Optionen:

      • Version 1: Verwenden Sie das ursprüngliche REST-Verhalten—Insert-Ereignisse werden nicht durch New-Ereignisse eingeleitet. (Standard für Endpunkte, die mit App Builder 4.50 und früher erstellt wurden.)

      • Version 2: Verwenden Sie ein verbessertes REST-Verhalten—New-Ereignisse und alle Standardregeln werden vor Insert-Ereignissen aufgerufen. (Standard für Endpunkte, die mit App Builder 4.51 erstellt wurden.)

      • Version 3: (Seit App Builder 4.52.) Identisch mit Version 2, aber APIs geben den logischen Wert statt des Speicherwerts zurück. Beispielsweise werden boolesche Werte als true oder false statt als 1 oder 0 zurückgegeben. (Standard für Endpunkte, die mit App Builder 4.52 und später erstellt wurden.)

  8. Klicken Sie auf Speichern.

Schritt 6: API-Schlüssel für einen Benutzer erstellen, um auf diesen Webhook zuzugreifen

Gehen Sie wie folgt vor, um einen API-Schlüssel zu erstellen (um einem Benutzer Zugriff auf diesen Webhook zu gewähren):

  1. Wählen Sie IDE > Benutzerverwaltung.

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

    user dialog

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

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

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

    • Anbieter: Wählen Sie APIKey.

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

user dialog

Schritt 7: Test

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

Verwenden Sie für Tests 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://{{user's identifier from Step 6}}:{{user's key from Step 6}}@{{url from Step 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 Nutzlast 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}} (zu verwenden, wenn der Anbieter API Key ist und die Eigenschaften den HttpHeaderName 'X-API-Key' enthalten)

Fehlerbehebung

Weitere Informationen zur Fehlerbehebung finden Sie in den folgenden Abschnitten im App-Builder-Fehlerbehebungsleitfaden: