Webhooks im Jitterbit App Builder

Übersicht

App Builder unterstützt die Möglichkeit, ein Ereignis als Antwort auf eine Email, eine Textnachricht oder einen API Aufruf auszulösen, um an App Builder Endpoint mithilfe von Webhooks. Webhooks sind benutzerdefinierte HTTP-Rückrufe und werden normalerweise durch ein Ereignis ausgelöst. Wenn das angegebene Ereignis eintritt, sendet die Quellsite eine HTTP-Anforderung an die für den Webhook konfigurierte URL.

Ein Beispiel für einen Webhook in App Builder ist wenn an App Builder Die Anwendung sendet eine Email an einen Benutzer mit der Aufforderung, eine Überweisung zu genehmigen oder abzulehnen. Der Benutzer antwortet auf die Email, indem er entweder „genehmigen“ oder „ablehnen“ in den Nachrichtentext eingibt. Wenn der Benutzer mit „genehmigen“ antwortet, App Builder löst ein Ereignis aus; „ablehnen“ löst ein anderes Ereignis aus. Mit dieser Funktion kann der Benutzer auf die Email oder Textnachricht antworten, ohne die Anwendung zu verlassen.

So konfigurieren Sie einen Webhook

In diesem Beispiel haben wir an App Builder Anwendung, die zur Auftragsverwaltung verwendet wird. Der Benutzer möchte über einen API Aufruf einen neuen Auftrag erstellen und die Auftragsnummer in der API Antwort erhalten können. Der Zweck des Webhooks besteht darin, einen neuen Auftragsdatensatz zu generieren, die Auftragsnummer zu berechnen und diese Auftragsnummer in der Antwort zurückzugeben.

Unsere Bestelltabelle enthält eine Bestell-ID (PK), einen Firmennamen, einen Produktnamen und eine Bestellnummer:

Schritt 1: Webhook in Datenservern hinzufügen

Server erstellen:
- Navigieren Sie zu IDE, Datenserver und klicken Sie auf +Server
- Weisen Sie einen Servernamen zu. Beispiel: OrderWebhook
- Wählen Sie unter Webdienste den Typ Webhook-API aus.
- Wählen Sie den entsprechenden Request/Response Content Type Content, in unserem Beispiel sind beide JSON
- Klicken Sie auf Speichern und schließen Sie das Popup:
Endpoint erstellen:
- Klicken Sie auf die Schaltfläche Datenserver Details
- Klicken Sie auf die Schaltfläche Endpoints
- Klicken Sie im Bereich „Endpoints“ auf + Endpoint
- Name Ihres Endpoint. Beispiel: PostOrder
  
  Notiz
  
  Dieser Name wird nicht in der Webhook URL angezeigt.
- Wählen Sie die HTTP-Methode aus, die Ihr Webhook verwendet. Normalerweise ist dies ein POST zum Aktualisieren von Informationen in einer Tabelle.
- Klicken Sie zum Speichern auf das Häkchen-Symbol
Endpoint erstellen:
- Klicken Sie im Bereich „Endpoints“ auf Erkennen
- Wenn der Webhook einen Text akzeptiert (z. B. einen POST mit JSON- oder XML-Anforderungsinhaltstyp), geben Sie ein Beispiel für einen Anforderungstext an. Für unser Beispiel lautet unser JSON:
```
{
    "Company": "Jitterbit",
    "Product": "App Builder"
}
```
  (Wir generieren die OrderID und OrderNumber als Teil der vom Webhook ausgelösten Ereignisse)
- Klicken Sie auf Speichern
- Klicken Sie auf Entdecken. Dadurch werden die eingegebenen Endpoint automatisch hinzugefügt.
Fügen Sie bei Bedarf den Endpoint „Antwort“ hinzu. In unserem Beispiel wäre dies der Typ „String“, die Länge –1 Zeichen, ohne Testwert, ohne ausgewählten Typ für „Cookie/Header/Abfrage“ und die Richtung wäre „Ausgabe“.

Schritt 2: Webhook zu Ihrer Anwendung hinzufügen

Navigieren Sie zu App Workbench > Datenquellen
Klicken Sie auf + Quelle
Wählen Sie Link zu vorhandener Quelle
Klicken Sie auf Weiter
Wählen Sie die in Schritt 1 konfigurierte REST Webhook-API aus
Klicken Sie auf die Schaltfläche Link
Überprüfen Sie die Zusammenfassung dessen, was App Builder wird ausgeführt und klicken Sie auf Fertig

Schritt 3: Erstellen einer Webhook-Geschäftsregel

Navigieren Sie zu App Workbench > Regeln.
Bestätigen Sie, dass die ausgewählte App-Datenquelle Ihre neu erstellte Webhook-Datenquelle und nicht Ihre Anwendungsdatenquelle ist.
Klicken Sie auf + Regel
Vergeben Sie einen Namen. Beispiel: Order (Webhook)
Wählen Sie Webhook als Zweck
Wählen Sie die Webhook-Datenquelle als Quelldatenquelle
Setzen Sie Ziel auf den Webhook-Endpoint
Klicken Sie auf Speichern
Fügen Sie Ihre Endpoint-Tabelle hinzu und wählen Sie alle Spalten aus. In unserem Beispiel ist dies die PostOrder-Tabelle.

Schritt 4: XP CRUD-Geschäftsregeln erstellen

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

Die Auftragstabelle muss öffentliches Lesen/Schreiben zulassen, was unter den Edge-Case-Einstellungen der Auftragstabelle im Tabellendesign konfigurierbar ist
Die Zielebene muss auf die Logikebene eingestellt sein

Wir werden eine Spalte hinzufügen, um einen PK mithilfe des newuuid() Funktion und fügen Sie die Spalten „Unternehmen“ und „Produkt“ aus unserem Webhook-Objekt mit entsprechenden Zielen hinzu:

Hinweis

Wir müssen die Bestellnummer nicht hinzufügen, da diese als Teil des Einfügeereignisses der Bestelltabelle generiert wird

Schritt 5: Erstellen einer XP CRUD-Geschäftsregel

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

Erstellen Sie eine neue XP CRUD-Regel, die bei der Webhook-Datenquelle registriert ist. Zum Beispiel PostOrder (Update Response)
Setzen Sie die Aktion auf Update
Quelldatenquelle auf die Datenquelle Ihrer Anwendung
Zieldatenquelle auf die Datenquelle Ihres Webhooks
Setzen Sie die Zielebene auf Logikebene
Setzen Sie das Ziel auf Ihr Webhook-Objekt. Zum Beispiel Order Webhook
Fügen Sie die Bestelltabelle aus der Anwendungsdatenquelle hinzu
Fügen Sie die Spalte OrderNumber hinzu, die auf die Spalte Response abzielt
Fügen Sie eine Where-Klausel hinzu, die basierend auf der neu generierten Bestellung filtert (wir verwenden die generierte Funktion, um die in diesem Ereignis generierte OrderID abzurufen)

Hinweis

Die generierte Funktion gibt einen String zurück, daher müssen wir die Bestell-ID als String umwandeln, damit dies funktioniert

Schritt 6: CRUD-Geschäftsregeln als Aktionen hinzufügen

Fügen Sie die beiden erstellten CRUD-Geschäftsregeln zum Logic Layer Insert Event der Webhook-Geschäftsregel hinzu.

Schritt 7: Webhook der Welt zugänglich machen

Erstellen Sie einen Endpoint für Ihre Anwendung. Möglicherweise wurde dies für Ihre Anwendung bereits erledigt.

Navigieren Sie zu App Builder IDE > REST- APIs (unter Verbinden) > Webhooks
Klicken Sie auf die Schaltfläche Endpoints verwalten
Wählen Sie die Anwendung aus, für die Sie den Endpoint eingeben möchten. Beispiel: WebhookDocumentation.
Klicken Sie auf das Bleistift-Bearbeitungssymbol für die Anwendung, die Sie konfigurieren
Geben Sie den Endpoint in das Feld Endpoint ein. Zum Beispiel WebhookDoc
Klicken Sie auf Weiter, um zu speichern
Um das Webhook-Objekt zu konfigurieren, klicken Sie im Webhooks-Panel auf +Webhook
Wählen Sie Ihr Webhook-Objekt aus. Es wird automatisch ein Endpoint ausgewählt. Dies wird der Webhook-Teil der Webhook URL.
Klicken Sie auf Speichern

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

Wir erstellen einen einfachen API Schlüssel und weisen ihn einem Benutzer zu, der auf diesen Webhook zugreifen kann. Dies kann einmal für einen Servicebenutzer oder mehrmals für einzelne Benutzer erfolgen.

Navigieren Sie zur IDE, Sicherheitsanbieter
Erstellen Sie unter Benutzerauthentifizierung einen Eintrag vom Typ HTTP-Basisauthentifizierung, falls noch keiner vorhanden ist. Wenn ja, können Sie diesen Schritt überspringen.
Navigieren Sie zu IDE, Benutzerverwaltung
Wählen Sie den Benutzer aus, der einen Schlüssel benötigt
Klicken Sie unter Authentifizierung auf Schlüssel
Klicken Sie auf Erstellen
Wählen Sie als Provider den Sicherheitsanbieter vom Typ HTTP Basic Authentication aus den Schritten 1 und 2 aus.
Klicken Sie auf Speichern
Notieren Sie sich den generierten Identifikator und Schlüssel, da diese Informationen nicht erneut verfügbar sein werden

Schritt 9: Testen

Sie können diesen Webhook mit Postman oder Insomnia testen. Senden Sie einen POST- API Aufruf mit einem Textkörper, der dem Textkörperbeispiel ähnelt, das zum Erstellen der Parameter in Schritt 1 verwendet wurde. Sie verwenden die Basisauthentifizierung mit der Kennung als Benutzername und dem Schlüssel als Kennwort aus dem vorherigen Schritt.

Zum Testen nutzen Sie bitte 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-Schlüssels im Header die URL möglicherweise auf eine dieser Optionen anpassen:

https://{{Benutzerkennung aus Schritt 8.9}}:{{Benutzerschlüssel aus Schritt 8.9}}@{{url von Schritt9}}(zu verwenden, wenn der Anbieter HTTP-Basisauthentifizierung ohne Parameter ist)

Vorsicht

Die oben beschriebene HTTP-Basismethode erfordert, dass der Header in der empfangenen Payload enthalten ist. Um dies zu umgehen, verwenden Sie stattdessen die API Schlüsselmethode.
https://{{url von Schritt9}}?apiKey={{Benutzerschlüssel aus Schritt 8.9}} (zu verwenden, wenn der Anbieter ein API Schlüssel ist und die Eigenschaften HttpHeaderName enthalten 'X-API-Key ')