Zum Inhalt springen

Verwandeln Sie Ihre Kontakte in Urlaubsgeld mit unserem neuen Kundenempfehlungsprogramm! Erfahren Sie mehr

✕

Diese Dokumentation gilt für Version 4 und höher von App Builder, dem neuen Namen für Vinyl. Hier gelangen Sie zur Vinyl-Dokumentation.

✕

Webhooks im Jitterbit App Builder

Übersicht

App Builder unterstützt die Auslösung eines Ereignisses als Reaktion auf eine Email, eine SMS oder einen API Aufruf an einen App Builder Endpoint mithilfe von Webhooks. Webhooks sind benutzerdefinierte HTTP-Rückrufe und werden typischerweise durch ein Ereignis ausgelöst. Tritt das angegebene Ereignis ein, sendet die Quellsite eine HTTP-Anfrage an die für den Webhook konfigurierte URL.

Ein Beispiel für einen Webhook im App Builder ist, wenn die App Builder-Anwendung einem Benutzer eine Email sendet und ihn auffordert, eine Überweisung zu genehmigen oder abzulehnen. Der Benutzer antwortet auf die Email mit „Genehmigen“ oder „Ablehnen“. Antwortet der Benutzer mit „Genehmigen“, löst App Builder ein Ereignis aus; antwortet er mit „Ablehnen“, wird ein anderes Ereignis ausgelöst. 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 verwenden wir eine App Builder-Anwendung zur Auftragsverwaltung. Der Benutzer möchte per API -Aufruf eine neue Bestellung erstellen und die Bestellnummer in der API Antwort erhalten. Der Webhook generiert einen neuen Bestelldatensatz, berechnet die Bestellnummer und gibt diese in der Antwort zurück.

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

Bestelltabelle.png

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

      orderdataserver.png

  2. Endpoint erstellen:

    • Klicken Sie auf die Schaltfläche Datenserver Details
    • Klicken Sie auf die Schaltfläche Endpoints
    • Klicken Sie im Bereich „Endpoints “ auf + Endpoint

    • Benennen Sie Ihren 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

  3. Endpoint erstellen:

    • Klicken Sie im Bereich „Endpoints“ auf Erkennen

    • Wenn der Webhook einen Text akzeptiert (z. B. einen POST mit JSON- oder XML-Anforderungsinhalt), geben Sie einen Beispiel-Anforderungstext an. In unserem Beispiel lautet unser JSON:

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

      (Wir generieren die Bestell-ID und Bestellnummer als Teil der vom Webhook ausgelösten Ereignisse.)

      webhookendpoint.png

    • Klicken Sie auf Speichern

    • Klicken Sie auf Entdecken. Dadurch werden die eingegebenen Endpoint automatisch hinzugefügt.

  4. Fügen Sie bei Bedarf den Endpoint „Antwort“ hinzu. In unserem Beispiel wäre dies der Typ „String“, die Länge –1 Zeichen, kein Testwert, kein ausgewählter Typ für „Cookie/Header/Abfrage“ und die Richtung „Ausgabe“.

Schritt 2: Webhook zu Ihrer Anwendung hinzufügen

  1. Navigieren Sie zu App Workbench > Datenquellen
  2. Klicken Sie auf + Quelle
  3. Wählen Sie Link zu vorhandener Quelle
  4. Klicken Sie auf Weiter
  5. Wählen Sie die in Schritt 1 konfigurierte REST Webhook API aus
  6. Klicken Sie auf die Schaltfläche Link
  7. Überprüfen Sie die Zusammenfassung der Funktionen des App Builder und klicken Sie auf Fertig

Schritt 3: Erstellen einer 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.

    appdatasources.png

  4. Vergeben Sie einen Namen. Beispiel: Bestellung (Webhook)

  5. Wählen Sie Webhook als Zweck
  6. Wählen Sie die Webhook-Datenquelle als Quelldatenquelle
  7. Setzen Sie Ziel auf den Webhook Endpoint
  8. Klicken Sie auf Speichern
  9. 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. Diese Regel sollte wie das soeben erstellte Webhook-Objekt in der Webhook-Datenquelle registriert sein. Hinweise:

  • Die Auftragstabelle muss öffentliche Lese-/Schreibzugriffe zulassen. Dies ist in den Edge-Case-Einstellungen der Auftragstabelle im Tabellendesign konfigurierbar.
  • Die Zielebene muss auf die Logikebene eingestellt sein.

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

orderxpcrud.png

xpcolumns.png

Hinweis

Die Bestellnummer muss nicht hinzugefügt werden, da sie im Rahmen des Insert-Ereignisses der Tabelle „Bestellung“ generiert wird.

Schritt 5: Erstellen einer XP CRUD-Geschäftsregel

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

  1. Erstellen Sie eine neue XP-CRUD-Regel, die in der Webhook-Datenquelle registriert ist. Beispiel: PostOrder (Update-Antwort).
  2. Setzen Sie die Aktion auf Aktualisieren.
  3. Setzen Sie die Quelldatenquelle auf die Datenquelle Ihrer Anwendung.
  4. Setzen Sie die Zieldatenquelle auf die Datenquelle Ihres Webhooks.
  5. Setzen Sie die Zielebene auf Logikebene.
  6. Setzen Sie das Ziel auf Ihr Webhook-Objekt. Beispiel: Order Webhook.
  7. Fügen Sie die Tabelle „Bestellung“ aus der Anwendungsdatenquelle hinzu.
  8. Fügen Sie die Spalte „Bestellnummer“ hinzu, die auf die Spalte „Antwort“ abzielt.

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

    postxpexample.png

Hinweis

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

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

Fügen Sie die beiden erstellten CRUD-Geschäftsregeln zum Einfügeereignis der Logikebene der Webhook-Geschäftsregel hinzu.

insertevent.png

Schritt 7: Webhook der Welt zugänglich machen

Erstellen Sie einen Endpoint für Ihre Anwendung. Dies ist möglicherweise bereits für Ihre Anwendung geschehen.

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

  9. Klicken Sie auf Speichern

    exposewebhook.png

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 für den Zugriff auf diesen Webhook zu. Dies kann einmalig für einen Servicebenutzer oder mehrmals für einzelne Benutzer erfolgen.

  1. Navigieren Sie zur IDE, Sicherheitsanbieter
  2. Erstellen Sie unter Benutzerauthentifizierung einen Eintrag vom Typ HTTP-Basisauthentifizierung, falls noch keiner vorhanden ist. Falls ja, 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 Provider den Sicherheitsanbieter vom Typ HTTP Basic Authentication aus den Schritten 1 und 2
  8. Klicken Sie auf Speichern
  9. Notieren Sie sich die generierte Kennung und den Schlüssel, da diese Informationen nicht wieder 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 Text, der dem Textbeispiel ä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 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-Schlüssels 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 from step9}}(Zu verwenden, wenn der Provider HTTP Basic Auth ohne Parameter verwendet)

    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.

  2. https://{{url from step9}}?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')