Webhook-Ereignisbereitstellung

Artikel
09/25/2023

Ein Webhook ist eine der vielen Möglichkeiten, um Ereignisse aus Azure Event Grid zu empfangen. Wenn ein neues Ereignis bereit ist, sendet der Event Grid-Dienst per POST-Vorgang eine HTTP-Anforderung an den konfigurierten Endpunkt, wobei die Ereignisinformationen im Anforderungstext enthalten sind.

Wie viele andere Dienste, die Webhooks unterstützen, müssen Sie bei Event Grid nachweisen, das Sie im Besitz Ihres Webhookendpunkts sind. Vorher wird mit dem Bereitstellen von Ereignissen für diesen Endpunkt nicht begonnen. Diese Anforderung verhindert, dass ein böswilliger Benutzer Ihren Endpunkt mit Ereignissen überschwemmt.

Endpunktüberprüfung mit Event Grid-Ereignissen

Wenn Sie einen der drei folgenden Azure-Dienste verwenden, wird diese Überprüfung automatisch von der Azure-Infrastruktur durchgeführt:

Azure Logic Apps mit Event Grid-Connector
Azure Automation über Webhook
Azure Functions mit Event Grid-Trigger

Falls Sie einen anderen Typ von Endpunkt nutzen, z. B. eine auf einem HTTP-Trigger basierende Azure-Funktion, muss Ihr Endpunktcode an einem Überprüfungshandshake mit Event Grid beteiligt sein. Event Grid unterstützt zwei Methoden zur Überprüfung des Abonnements.

Synchroner Handshake: Zum Zeitpunkt der Erstellung des Ereignisabonnements sendet Event Grid ein Ereignis zur Überprüfung des Abonnements an Ihren Endpunkt. Das Schema dieses Ereignisses ähnelt dem aller anderen Event Grid-Ereignisse. Der Datenteil dieses Ereignisses umfasst eine validationCode-Eigenschaft. Ihre Anwendung überprüft, ob es sich bei der Überprüfungsanforderung um ein erwartetes Ereignisabonnement handelt, und gibt den Überprüfungscode synchron in der Antwort zurück. Dieser Handshakemechanismus wird in allen Event Grid-Versionen unterstützt.
Asynchroner Handshake: In bestimmten Fällen können Sie den validationCode nicht synchron in der Antwort zurückgeben. Wenn Sie beispielsweise einen Drittanbieterdienst nutzen (z. B. Zapier oder IFTTT), können Sie unter Umständen nicht programmgesteuert mit dem Überprüfungscode antworten.

Event Grid unterstützt einen manuellen Überprüfungshandshake. Wenn Sie ein Ereignisabonnement mit einem SDK oder Tool erstellen, für die diese neue API-Version (2018-05-01-preview oder höher) verwendet wird, sendet Event Grid im Datenteil des Abonnementüberprüfungsereignisses eine validationUrl-Eigenschaft. Um den Handshake abzuschließen, suchen Sie diese URL in den Ereignisdaten und senden ihr eine GET-Anforderung. Sie können entweder einen REST-Client oder Ihren Webbrowser verwenden.

Die angegebene URL ist 10 Minuten lang gültig. Während dieser Zeit lautet der Bereitstellungsstatus des Ereignisabonnements AwaitingManualAction. Wenn Sie die manuelle Überprüfung nicht innerhalb von 10 Minuten abschließen, wird der Bereitstellungsstatus auf Failed eingestellt. Sie müssen das Ereignisabonnement erneut erstellen, bevor Sie mit der manuellen Überprüfung beginnen.

Dieser Authentifizierungsmechanismus erfordert auch, dass der Webhookendpunkt einen HTTP-Statuscode von 200 zurückgibt, um sicherzustellen, dass das POST für das Überprüfungsereignis akzeptiert wurde, bevor er in den manuellen Überprüfungsmodus gewechselt wird. Mit anderen Worten: Wenn der Endpunkt 200 zurückgibt, aber nicht synchron eine Überprüfungsantwort zurückgibt, wird der Modus in den manuellen Überprüfungsmodus überführt. Wenn innerhalb von 10 Minuten ein GET-Vorgang auf die Überprüfungs-URL folgt, gilt der Überprüfungshandshake als erfolgreich.

Hinweis

Die Verwendung von selbstsignierten Zertifikaten wird nicht unterstützt. Verwenden Sie stattdessen ein signiertes Zertifikat von einer kommerziellen Zertifizierungsstelle.

Überprüfungsdetails

Zum Zeitpunkt der Erstellung/Aktualisierung des Ereignisabonnements sendet Event Grid ein Abonnementüberprüfungsereignis an den Zielendpunkt.
Das Ereignis enthält einen aeg-event-type: SubscriptionValidation-Headerwert.
Der Hauptteil des Ereignisses weist dasselbe Schema wie andere Event Grid-Ereignisse auf.
Die eventType-Eigenschaft des Ereignisses lautet Microsoft.EventGrid.SubscriptionValidationEvent.
Die data-Eigenschaft des Ereignisses enthält eine validationCode-Eigenschaft mit einer zufällig generierten Zeichenfolge. Beispiel: validationCode: acb13….
Die Ereignisdaten enthalten auch die validationUrl-Eigenschaft mit einer URL für die manuelle Überprüfung des Abonnements.
Das Array enthält ausschließlich das Validierungsereignis. Andere Ereignisse werden in einer separaten Anforderung gesendet, nachdem Sie den Validierungscode zurückgegeben haben.
Die EventGrid-SDKs der Datenebene verfügen über Klassen, die den Daten des Abonnementüberprüfungsereignisses und der Abonnementüberprüfungsantwort entsprechen.

Ein Beispiel für „SubscriptionValidationEvent“ finden Sie im folgenden Beispiel:

[
  {
    "id": "2d1781af-3a4c-4d7c-bd0c-e34b19da4e66",
    "topic": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "subject": "",
    "data": {
      "validationCode": "512d38b6-c7b8-40c8-89fe-f46f9e9622b6",
      "validationUrl": "https://rp-eastus2.eventgrid.azure.net:553/eventsubscriptions/myeventsub/validate?id=0000000000-0000-0000-0000-00000000000000&t=2022-10-28T04:23:35.1981776Z&apiVersion=2018-05-01-preview&token=1A1A1A1A"
    },
    "eventType": "Microsoft.EventGrid.SubscriptionValidationEvent",
    "eventTime": "2022-10-28T04:23:35.1981776Z",
    "metadataVersion": "1",
    "dataVersion": "1"
  }
]

Senden Sie wie im folgenden Beispiel gezeigt den Validierungscode zurück an die Eigenschaft validationResponse, um den Besitz des Endpunkts nachzuweisen:

{
  "validationResponse": "512d38b6-c7b8-40c8-89fe-f46f9e9622b6"
}

Und führen Sie einen der folgenden Schritte aus:

Sie müssen den Antwortstatuscode HTTP 200 OK zurückgeben. HTTP 202 Accepted wird nicht als gültige Antwort zur Überprüfung des Event Grid-Abonnements erkannt. Die HTTP-Anforderung muss innerhalb von 30 Sekunden abgeschlossen werden. Wenn der Vorgang nicht innerhalb von 30 Sekunden abgeschlossen wird, wird er abgebrochen und kann nach 5 Sekunden wiederholt werden. Wenn alle Versuche zu Fehlern führen, wird dies als Handshake-Überprüfungsfehler gewertet.

Die Tatsache, dass Ihre Anwendung darauf vorbereitet ist, den Überprüfungscode zu verarbeiten und zurückzugeben, zeigt, dass Sie das Ereignisabonnement erstellt haben und den Empfang des Ereignisses erwarten. Stellen Sie sich das Szenario vor, dass keine Handshakeüberprüfung unterstützt wird und ein Hacker die URL Ihrer Anwendung ermittelt. Der Hacker kann ein Thema und ein Ereignisabonnement mit der URL Ihrer Anwendung erstellen und einen DoS-Angriff auf Ihre Anwendung durchführen, indem er eine Vielzahl von Ereignissen sendet. Die Handshakeüberprüfung verhindert dies.

Stellen Sie sich vor, dass Sie die Überprüfung bereits in Ihrer App implementiert haben, da Sie Ihre eigenen Ereignisabonnements erstellt haben. Selbst wenn ein Hacker ein Ereignisabonnement mit Ihrer App-URL erstellt, wird Ihre korrekte Implementierung des Überprüfungsanforderungsereignisses auf den aeg-subscription-name-Header in der Anforderung prüfen, um sicherzustellen, dass es sich um ein Ereignisabonnement handelt, das Sie erkennen.

Selbst nach dieser korrekten Handshakeimplementierung kann ein Hacker einen Floodingangriff auf Ihre App starten (sie hat das Ereignisabonnement bereits überprüft), indem er eine Anforderung repliziert, die scheinbar von Event Grid stammt. Um dies zu verhindern, müssen Sie Ihren Webhook mit der Microsoft Entra-Authentifizierung sichern. Weitere Informationen finden Sie unter Bereitstellen von Ereignissen auf mit Microsoft Entra geschützten Endpunkten.
Alternativ können Sie das Abonnement manuell überprüfen, indem Sie eine GET-Anforderung an die Überprüfungs-URL senden. Das Ereignisabonnement bleibt im Status „Ausstehend“, bis es überprüft wurde. Die Überprüfungs-URL verwendet den Port 553. Wenn Ihre Firewallregeln Port 553 blockieren, müssen Sie die Regeln für einen erfolgreichen manuellen Handshake aktualisieren.

Wenn Sie bei der Überprüfung des Ereignisses zur Abonnementüberprüfung feststellen, dass es sich nicht um ein Ereignisabonnement handelt, für das Sie Ereignisse erwarten, würden Sie keine 200-Antwort oder gar keine Antwort zurückgeben. Daher schlägt die Überprüfung fehl.

Ein Beispiel für die Handhabung des Handshakes zur Abonnementüberprüfung finden Sie in einem C#-Beispiel.

Endpunktüberprüfung mit CloudEvents 1.0

CloudEvents 1.0 implementiert eine eigene Semantik für den Schutz vor Missbrauch über die HTTP OPTIONS-Methode. Weitere Informationen dazu finden Sie hier. Wenn Sie das CloudEvents-Schema für die Ausgabe nutzen, verwendet Event Grid anstelle des Event Grid-Mechanismus für Überprüfungsereignisse den Missbrauchschutz von CloudEvents v1.0.

Ereignisschemakompatibilität

Wenn ein Thema erstellt wird, wird ein Schema für eingehende Ereignisse definiert. Wenn ein Abonnement erstellt wird, wird ein Schema für ausgehende Ereignisse definiert. Die folgende Tabelle zeigt die Kompatibilität, die beim Erstellen eines Abonnements zulässig ist.

Schema für eingehende Ereignisse	Schema für ausgehende Ereignisse	Unterstützt
Event Grid-Schema	Event Grid-Schema	Yes
	Cloud Events v1.0-Schema	Yes
	Benutzerdefiniertes Eingabeschema	No
Cloud Events v1.0-Schema	Event Grid-Schema	No
	Cloud Events v1.0-Schema	Yes
	Benutzerdefiniertes Eingabeschema	No
Benutzerdefiniertes Eingabeschema	Event Grid-Schema	Yes
	Cloud Events v1.0-Schema	Yes
	Benutzerdefiniertes Eingabeschema	Ja

Nächste Schritte

Im folgenden Artikel finden Sie Informationen zur Behandlung von Problemen bei der Überprüfung von Ereignisabonnements: Problembehandlung bei der Abonnementüberprüfung für Azure Event Grid.