Webhooktrigger

  • 5 Minuten

Webhooks sind beliebte HTTP-basierte Implementierungen eines allgemeineren Benachrichtigungsmusters zwischen Herausgeber und Abonnent. Sie bieten eine Möglichkeit, Benachrichtigungen an einen externen Dienst (Abonnenten) zu senden, wenn bestimmte Ereignisse innerhalb eines Systems (Herausgeber) auftreten.

Mit Power Automate und Azure Logic Apps können Entwickler Webhooks als Trigger verwenden. In diesem Szenario spielen Trigger die Rolle eines Abonnenten, der Webhooks im Namen eines Entwicklers registriert und die Registrierung aufhebt. Die Registrierung erfolgt, wenn ein Schritt in einem Cloud-Flow oder Logic Apps-Workflow erstellt oder aktualisiert wird. Wenn der Schritt entfernt wird, hebt die Plattform die Registrierung des Webhooks auf.

Da Copilot Ihnen bei der Einrichtung Ihres Konnektors helfen kann, kann er Ihnen auch hier behilflich sein. Sie können mit einfachen Eingabeaufforderungen beginnen und Ihre Implementierung im Laufe der Zeit verbessern:

  • „Wie definiere ich einen HTTP Trigger für meinen benutzerdefinierten Konnektor?“

  • „Welche Parameter sollte ich in meinen benutzerdefinierten Konnektor-Trigger einbeziehen?“

  • „Kann meine Trigger-Logik auf mögliche Verbesserungen überprüft werden?“

Copilot kann Ihnen basierend auf Ihrer API und den Anforderungen des Flows die optimale Vorgehensweise beim Definieren der Trigger vorschlagen.

Der folgende Screenshot zeigt ein Beispiel für die Interaktion zwischen Abonnent und Herausgeber.

Diagramm der Interaktion zwischen Abonnent und Herausgeber

Die Verantwortlichkeiten der Parteien sind in der folgenden Tabelle aufgeführt.

Herausgeber (benutzerdefinierter Konnektor OpenAPI) Abonnent (Power Automate/Logic Apps)
Stellt den Endpunkt für die Abonnementregistrierung bereit Ruft den Endpunkt der Abonnementregistrierung auf, wenn ein Trigger in einem Flow erstellt oder aktualisiert wird
Gibt den Benachrichtigungsvertrag an, d. h. welches Objekt bei jeder Benachrichtigung übergeben wird Muss den Standort-HTTP-Header zum Zeitpunkt der Erstellung eines Webhooks in die 201-Antwort aufnehmen Gibt die URL des automatisch generierten Endpunkts an, der die Benachrichtigungsnachrichten akzeptiert
Verwaltet das Abonnentenregister und deren Benachrichtigungsendpunkte Empfängt und speichert Standortinformationen, die zum Abmelden des Webhooks verwendet werden
Gibt eine POST-Anforderung an jeden registrierten Endpunkt aus und übergibt die relevanten Daten im Nachrichtentext Empfängt Benachrichtigungen, validiert sie anhand des vom benutzerdefinierten Konnektor definierten Schemas und löst dann die Automatisierung aus
Hebt die Registrierung der Endpunkte als Antwort auf die DELETE-Nachricht auf bzw. entfernt sie Gibt eine DELETE-Nachricht aus, um den Webhook abzumelden, wenn der Triggerschritt gelöscht wird

Webhooks bieten nur den Benachrichtigungsmechanismus und unterstützen keine Manipulation der Daten. Häufig wird eine Webhook-Implementierung durch eine oder mehrere Aktionen ergänzt, die das Abrufen und Bearbeiten von Daten oder Objekten unterstützen.

API-Anforderungen

Um die von benutzerdefinierten Konnektoren erforderliche Webhook-Unterstützung bereitzustellen, muss die API-Implementierung die folgenden Parameter bereitstellen:

  • Ein Endpunkt, der die Registrierungsnachricht akzeptiert und Standortinformationen zurückgibt

  • Eine Definition des Nachrichtentexts, der mit den Benachrichtigungsnachrichten gesendet wird

  • Ein Endpunkt zum Akzeptieren der DELETE-Nachricht zum Entfernen der Webhook-Registrierung

Normalerweise verwaltet die API-Implementierung eine interne Liste aktiver Abonnenten, wobei jeder Abonnent durch eine eindeutige URL identifiziert wird. Um diese URL an den Abonnenten zurückzugeben, muss die erfolgreiche Webhook-Erstellung eine HTTP 201-Antwort zurückgeben und einen Ort-HTTP-Header enthalten. Der Wert dieses Speicherorts wird später vom Abonnenten verwendet, um die Webhook-Registrierung zu löschen.

Einen Webhooktrigger verwenden

Benutzerdefinierte Konnektoren verwenden OpenAPI, um die von Webhooks geforderte Herausgeber-API-Implementierung zu beschreiben. Um einen Webhook-Trigger in einem benutzerdefinierten Konnektor zu definieren, müssen Sie drei wesentliche Teile in die OpenAPI-Definition aufnehmen:

  • Eine POST-Nachricht, die die Registrierung von Webhooks beschreibt

  • Inhaltsdefinition für die Webhook-Antworten

  • Eine DELETE-Nachricht, die den Webhook-Abrissprozess beschreibt

Registrierungsnachricht

Die Triggerdefinition muss eine POST-Methode enthalten, mit der ein Webhook registriert wird. Sie ist ähnlich wie Aktionen definiert.

Screenshot der Entwicklerumgebung für das Design von benutzerdefinierten Konnektoren. Ein neuer Trigger wird definiert und das HTTP-Verb POST und die URL werden als Schlüsselelemente der Triggerdefinition hervorgehoben.

Die OpenAPI-Spezifikationsversion, die von Microsoft Power Platform verwendet wird, unterscheidet keine Aktionen und Trigger. Die benutzerdefinierte Konnektordefinition verwendet die benutzerdefinierte x-ms-Trigger-Erweiterung zum Deklarieren eines Triggers.

paths:
  /webhooks:
    post:
      operationId: OrderCreated
      x-ms-trigger: single

Die Anwesenheit der x-ms-Trigger-Erweiterung gibt an, dass die Methode ein Trigger und keine Aktion ist. Diese Erweiterung wird automatisch hinzugefügt, wenn mit dem Assistenten ein Trigger erstellt wird. Wenn jedoch aus den externen OpenAPI-Definitionen ein benutzerdefinierter Konnektor erstellt wird, werden beim Importvorgang immer Aktionen erstellt. In diesem Szenario müssen Sie Trigger mithilfe des Assistenten neu erstellen und dann die entsprechenden Aktionsdefinitionen entfernen.

Mögliche Werte für die x-ms-Trigger-Erweiterung sind einzeln oder als Batch, um zwischen einem Objekt und Array-Antworten zu unterscheiden. Ein einzelnes Objekt ist enthalten, wenn ein Webhook für jede Änderung eine Benachrichtigung auslöst. Dieser Ansatz ist bei Webhooks am gebräuchlichsten. Wenn mehrere Änderungen zu einer einzigen Benachrichtigung zusammengefasst werden, wird ein Array von Objekten gesendet. Dieser Ansatz wird normalerweise bei Abruftriggern verwendet und wird später in diesem Modul erläutert.

Webhook-Antwort

Definitionen zu benutzerdefinierten Konnektoren können den Inhalt der eingehenden Webhook-Antworten Ihres Dienstes beschreiben, wenn ein Ereignis auftritt. Diese Definition ist zwar nicht obligatorisch, identifiziert jedoch die dynamischen Werte, die dem Entwickler zur Entwurfszeit zur Verfügung stehen, in der Liste der dynamischen Inhalte.

Hinweis

Diese Antwort bezieht sich nicht auf die Anforderung, mit der der Webhook erstellt und registriert wird. Diese Daten werden von Ihrem Dienst gesendet, wenn ein Ereignis eintritt.

Screenshot der Webhook-Antwort mit hervorgehobenem Feld „Textkörper“

Die benutzerdefinierte Eigenschaft x-ms-Benachrichtigungsinhalt ist eine weitere Erweiterung, die in OpenAPI zum Definieren des Webhook-Antwortschemas verwendet wird.

paths:
  /webhooks:
    x-ms-notification-content:
      description: Order
      schema:
        type: object
        properties:
          id: {type: integer, format: int32, description: id}
          order_key: {type: string, description: order_key}
          status: {type: string, description: status}
          currency: {type: string, description: currency}
          date_created: {type: string, description: date_created}
          total: {type: number, description: total, format: decimal}

Tipp

Eine Webhook-Antwortdefinition muss nicht den gesamten Inhalt der Antwort enthalten, sondern nur die Teile, die Sie den Flowentwicklern zur Entwurfszeit in der dynamischen Inhaltsliste zur Verfügung stellen möchten.

Daten, die mit der Webhook-Antwort gesendet werden, müssen möglicherweise nicht alle Eigenschaften enthalten, und tun dies auch nicht, die Sie vom zugrunde liegenden Objekt benötigen. In diesen Situationen möchten Sie im benutzerdefinierten Konnektor andere Aktionen zum Abrufen von Informationen erstellen. Beispielsweise sendet ein Webshop möglicherweise nur eine neue Bestellkennung mit der Benachrichtigung „Wenn ein neuer Auftrag erstellt wird“. Anschließend kann der benutzerdefinierte Konnektor eine Aktion definieren, z. B. „Bestelldetails abrufen“, die eine Auftragskennung akzeptiert und erweiterte Informationen zum Auftrag zurückgibt.

Das Gegenteil ist auch der Fall. Webhook-Antworten enthalten möglicherweise übermäßige Informationen, die unter normalen Umständen nicht erforderlich oder benötigt sind. Sie müssen nur die Daten beschreiben, die Sie in den Entwickleroberflächen Power Automate oder Logic Apps anzeigen möchten. Wenn der Entwickler Zugriff auf weitere Daten benötigt, die in der Benachrichtigung gesendet werden, kann er JSON-Funktionen verwenden, um diese Eigenschaften direkt aus der empfangenen Nachricht zu extrahieren.

Nachricht löschen

Um für Power Automate oder Logic Apps einen Webhook zu löschen, muss die API einen Speicherort-HTTP-Header in der Antwort zum Zeitpunkt der Erstellung des Webhooks enthalten.

Wichtig

Sie müssen den Pfad der Anforderung zum Löschen von Webhooks als interne Aktion definieren. Diese Aktion sendet eine DELETE-Anforderung an die in der Kopfzeile des Speicherorts angegebene URL.

Wenn diese Aktion nicht definiert ist oder wenn die API die Kopfzeile für den Speicherort nicht enthält, werden Webhooks erstellt, aber nicht gelöscht. Dies kann zur Laufzeit zu Problemen bei der API-Implementierung führen.

Die Implementierung von Webhooks bietet einen flexiblen Mechanismus zur Unterstützung von Triggern in einem benutzerdefinierten Konnektor. Jedoch nicht jede API unterstützt Webhook-Integrationen. Die Abrufimplementierung bietet eine alternative Möglichkeit, Trigger in den benutzerdefinierten Konnektoren zu erstellen.