Webhooks im Jitterbit App Builder

Übersicht

Der App Builder unterstützt die Möglichkeit, ein Ereignis als Reaktion auf eine E-Mail, eine Textnachricht oder einen API-Aufruf an einen App Builder-Endpunkt über Webhooks auszulösen. Webhooks sind benutzerdefinierte HTTP-Callbacks und werden typischerweise durch ein Ereignis ausgelöst. Wenn das angegebene Ereignis eintritt, sendet die Quellseite eine HTTP-Anfrage an die für den Webhook konfigurierte URL.

Ein Beispiel für einen Webhook im App Builder ist, wenn eine App Builder-Anwendung eine E-Mail an einen Benutzer sendet, in der sie aufgefordert wird, einen Transfer zu genehmigen oder abzulehnen. Der Benutzer würde auf die E-Mail antworten und entweder "genehmigen" oder "ablehnen" in den Nachrichtentext eingeben. Wenn der Benutzer mit "genehmigen" antwortet, löst der App Builder ein Ereignis aus; bei "ablehnen" wird ein anderes Ereignis ausgelöst. Diese Funktion ermöglicht es dem Benutzer, auf die E-Mail oder Textnachricht zu antworten, ohne die Anwendung zu verlassen.

So konfigurieren Sie einen Webhook

In diesem Beispiel haben wir eine App Builder-Anwendung, die für das Bestellmanagement verwendet wird. Der Benutzer möchte in der Lage sein, eine neue Bestellung über einen API-Aufruf zu erstellen und die Bestellnummer in der API-Antwort zu erhalten. Der Zweck des Webhooks besteht darin, einen neuen Bestelldatensatz zu generieren, die Bestellnummer zu berechnen und diese Bestellnummer in der Antwort zurückzugeben.

Unsere Bestelltabelle hat eine OrderID (PK), den Firmennamen, den Produktnamen und die Bestellnummer:

Schritt 1: Webhook in Datenservern hinzufügen

1. Server erstellen:

   • Navigieren Sie zu IDE, Datenserver und klicken Sie auf +Server
   • Weisen Sie einen Servernamen zu. Zum Beispiel: OrderWebhook
   • Wählen Sie den Typ als Webhook API unter Webdiensten
   • Wählen Sie den entsprechenden Request/Response Content Type, in unserem Beispiel sind beide JSON

   • Klicken Sie auf Speichern und schließen Sie das Popup:

     

2. Endpunkt erstellen:

   • Klicken Sie auf die Schaltfläche Details des Datenservers
   • Klicken Sie auf die Schaltfläche Endpunkte
   • Klicken Sie auf +Endpunkt im Endpunkte-Panel

   • Benennen Sie Ihren Endpunkt. Zum Beispiel: PostOrder

     Hinweis

     Dieser Name wird nicht in der Webhook-URL angezeigt.

   • Wählen Sie die HTTP Methode aus, die Ihr Webhook verwendet. Typischerweise handelt es sich um ein POST, um Informationen in einer Tabelle zu aktualisieren.

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

3. Erstellen Sie Endpunktparameter:

   • Klicken Sie auf Entdecken im Endpunkt-Panel.

   • Wenn der Webhook einen Body akzeptiert (z. B. ein POST mit JSON- oder XML-Anforderungsinhaltstyp), geben Sie einen Beispiel-Anforderungs-Body an. Für unser Beispiel lautet unser JSON:

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

     (Wir generieren die OrderID und die OrderNumber als Teil der durch den Webhook ausgelösten Ereignisse.)

     

   • Klicken Sie auf Speichern.

   • Klicken Sie auf Entdecken. Dies fügt automatisch die Eingabe-Endpunktparameter hinzu.

4. Wenn gewünscht, fügen Sie den Antwort-Endpunktparameter hinzu. In unserem Beispiel wäre dies vom Typ String, Länge -1 Zeichen, ohne Testwert, kein Typ für Cookie/Header/Query ausgewählt, und die Richtung ist Ausgabe.

Schritt 2: Fügen Sie den Webhook zu Ihrer Anwendung hinzu

1. Navigieren Sie zu App Workbench > Datenquellen.
2. Klicken Sie auf + Quelle.
3. Wählen Sie Verknüpfung zu vorhandener Quelle.
4. Klicken Sie auf Weiter.
5. Wählen Sie die REST Webhook-API, die in Schritt 1 konfiguriert wurde.
6. Klicken Sie auf die Verknüpfung-Schaltfläche.
7. Überprüfen Sie die Zusammenfassung dessen, was der App Builder ausführen wird, und klicken Sie auf Fertig.

Schritt 3: Erstellen Sie eine Webhook-Geschäftsregel

1. Navigieren Sie zu App Workbench > Regeln.
2. Bestätigen Sie, dass die ausgewählte App-Datenquelle Ihre neu erstellte Webhook-Datenquelle und nicht Ihre Anwendungsdatenquelle ist.

3. Klicken Sie auf + Regel.

   

4. Weisen Sie einen Namen zu. Zum Beispiel: Bestellung (Webhook).

5. Wählen Sie Webhook als Zweck.
6. Wählen Sie die Webhook-Datenquelle als Quell-Datenquelle.
7. Setzen Sie Ziel auf den Webhook-Endpunkt.
8. Klicken Sie auf Speichern.
9. Fügen Sie Ihre Endpunkt-Tabelle hinzu und wählen Sie alle Spalten aus. In unserem Beispiel ist dies die PostOrder-Tabelle.

Schritt 4: Erstellen von XP CRUD-Geschäftsregeln

Erstellen Sie eine XP CRUD-Geschäftsregel, die den Wert, der vom Webhook empfangen wurde, in eine Tabelle in der Datenquelle Ihrer Anwendung einfügt. Diese sollte wie das gerade erstellte Webhook-Objekt bei der Webhook-Datenquelle registriert werden. Einige Hinweise:

• Die Bestellungstabelle muss öffentliches Lesen/Schreiben zulassen, was in den Edge-Case-Einstellungen der Bestellungstabelle im Tabellendesign konfiguriert werden kann.
• Die Zielschicht muss auf Logikschicht eingestellt sein.

Wir werden eine Spalte hinzufügen, um einen PK mit der Funktion newuuid() zu generieren, und die Spalten Unternehmen und Produkt aus unserem Webhook-Objekt mit den entsprechenden Zielen hinzufügen:

Schritt 5: Erstellen einer XP CRUD-Geschäftsregel

Erstellen Sie eine XP CRUD-Geschäftsregel, die die Antwort mit der OrderNumber der neuen Bestellung aktualisiert und schreibt.

1. Erstellen Sie eine neue XP CRUD-Regel, die bei der Webhook-Datenquelle registriert ist. Zum Beispiel, PostOrder (Update Response)
2. Setzen Sie die Aktion auf Aktualisieren
3. Quell-Datenquelle auf die Datenquelle Ihrer Anwendung
4. Ziel-Datenquelle auf die Datenquelle Ihres Webhooks
5. Setzen Sie die Zielschicht auf Logikschicht
6. Setzen Sie das Ziel auf Ihr Webhook-Objekt. Zum Beispiel, Order Webhook
7. Fügen Sie die Bestellungstabelle aus der Datenquelle der Anwendung hinzu
8. Fügen Sie die OrderNumber-Spalte hinzu, die auf die Antwortspalte abzielt

9. Fügen Sie eine Where-Klausel hinzu, die basierend auf der neu generierten Bestellung filtert (wir nutzen die generierte Funktion, um die OrderID abzurufen, die in diesem Ereignis generiert wurde)

   

Schritt 6: Fügen Sie die CRUD-Geschäftsregeln als Aktionen hinzu

Fügen Sie die beiden erstellten CRUD-Geschäftsregeln dem Logikschicht-Ereignis "Einfügen" der Webhook-Geschäftsregel hinzu.

Schritt 7: Exponieren Sie den Webhook für die Welt

Erstellen Sie einen Endpunkt für Ihre Anwendung. Dies könnte bereits für Ihre Anwendung erledigt worden sein.

1. Navigieren Sie zu App Builder IDE > REST APIs (unter Verbinden) > Webhooks
2. Klicken Sie auf die Schaltfläche Endpunkte verwalten
3. Wählen Sie die Anwendung aus, für die Sie den Endpunktwert eingeben möchten. Zum Beispiel: WebhookDocumentation.
4. Klicken Sie auf das Bleistift-Bearbeitungssymbol für die Anwendung, die Sie konfigurieren.
5. Geben Sie den Endpunktwert in das Endpunktfeld ein. Zum Beispiel WebhookDoc.
6. Klicken Sie auf fortfahren, um zu speichern.
7. Um das Webhook-Objekt zu konfigurieren, klicken Sie im Webhook-Panel auf +Webhook
8. Wählen Sie Ihr Webhook-Objekt aus. Es wird automatisch ein Endpunktname ausgewählt. Dies wird der Webhook-Teil der Webhook-URL.

9. Klicken Sie auf Speichern

   

10. (Optional, seit App Builder 4.51.) Stellen Sie die Ressourcenskompatibilitätsoption ein:

    1. Klicken Sie auf das Symbol "Datensatz öffnen". Das Webhook-Popup öffnet sich.
    2. Öffnen Sie das Menü Kompatibilität und wählen Sie eine der folgenden Optionen:
    3. Version 1: Verwenden Sie das ursprüngliche REST-Verhalten—Einfügen-Ereignisse werden nicht von Neu-Ereignissen vorangestellt. (Standard für Endpunkte, die mit App Builder 4.50 und früher erstellt wurden.)
    4. Version 2: Verwenden Sie ein verbessertes REST-Verhalten—Neu-Ereignisse und alle Standardregeln werden vor Einfügen-Ereignissen aufgerufen. (Standard für Endpunkte, die mit App Builder 4.51 und später erstellt wurden.)

Schritt 8: Erstellen Sie einen API-Schlüssel für einen Benutzer, um auf dieses Webhook zuzugreifen

Wir erstellen einen grundlegenden API-Schlüssel und weisen ihn einem Benutzer zu, um auf dieses Webhook zuzugreifen. Dies kann einmal für einen Service-Benutzer oder mehrmals für einzelne Benutzer durchgeführt werden.

1. Navigieren Sie zu IDE, Sicherheitsanbieter
2. Erstellen Sie unter Benutzerauthentifizierung einen Datensatz vom Typ HTTP Basic Authentication, falls noch keiner vorhanden ist. Wenn bereits einer vorhanden ist, können Sie diesen Schritt überspringen.
3. Navigieren Sie zu IDE, Benutzerverwaltung
4. Wählen Sie den Benutzer aus, der einen Schlüssel benötigt
5. Klicken Sie unter Authentifizierung auf Schlüssel
6. Klicken Sie auf Erstellen
7. Wählen Sie für den Anbieter den Sicherheitsanbieter vom Typ HTTP Basic Authentication aus den Schritten 1 und 2 aus
8. Klicken Sie auf Speichern
9. Notieren Sie sich die generierte Kennung und Schlüssel, da diese Informationen nicht erneut verfügbar sein werden

Schritt 9: Testen

Sie können dieses Webhook mit Postman oder Insomnia testen. Senden Sie einen POST-API-Aufruf mit dem Body, der dem Body-Beispiel ähnelt, das verwendet wurde, um die Parameter in Schritt 1 zu erstellen. Sie verwenden die grundlegende Authentifizierung mit der Kennung als Benutzernamen und dem Schlüssel als Passwort aus dem vorherigen Schritt.

Für den Test verwenden Sie den Link: https://<url>/webhook/v1/<application-endpoint>/<endpoint>

In dem Szenario, in dem keine Authentifizierung erforderlich ist, können Sie anstelle der Konfiguration eines x-api-key im Header die URL möglicherweise auf eine dieser Optionen anpassen:

1. https://{{Benutzerkennung aus Schritt 8.9}}:{{Benutzerschlüssel aus Schritt 8.9}}@{{url aus Schritt 9}} (zu verwenden, wenn der Anbieter HTTP Basic Auth ohne Parameter ist)

   Vorsicht

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

2. https://{{url aus Schritt 9}}?apiKey={{Benutzerschlüssel aus Schritt 8.9}} (zu verwenden, wenn der Anbieter API-Schlüssel ist und die Eigenschaften den HttpHeaderName 'X-API-Key' enthalten)