Erstellen ausgehender Webhooks

Der ausgehende Webhook fungiert als Bot und sucht mithilfe von @mention in Kanälen nach Nachrichten. Er sendet Benachrichtigungen an einen externen Webdienst und antwortet mit umfangreichen Nachrichten, die Karten und Bilder enthalten. Es hilft, den Erstellungsprozess von Bots über die Microsoft Bot Framework zu überspringen.

Im folgenden Video erfahren Sie, wie Sie ausgehende Webhooks erstellen:

Wichtige Features von ausgehenden Webhooks

Die folgende Tabelle enthält die Features und die Beschreibung ausgehender Webhooks:

Features	Beschreibung
Konfigurationsbereich	Webhooks werden auf Teamebene definiert. Der obligatorische Setupprozess für jeden fügt einen ausgehenden Webhook hinzu.
Reaktives Messaging	Benutzer müssen @mention verwenden, damit der Webhook Nachrichten empfangen kann. Die Benutzer können einen ausgehenden Webhook nur in öffentlichen Kanälen und nicht innerhalb des persönlichen oder privaten Bereichs senden.
Standard-HTTP-Nachrichtenaustausch	Antworten werden in derselben Kette wie die ursprüngliche Anforderungsnachricht angezeigt und können beliebige Bot Framework-Nachrichteninhalte enthalten. Beispielsweise Rich-Text, Bilder, Karten und Emojis. Ausgehende Webhooks können zwar Karten, jedoch keine Kartenaktionen (mit Ausnahme von openURL) verwenden.
Unterstützung der Teams-API-Methode	Ausgehende Webhooks senden einen HTTP POST an einen Webdienst und erhalten eine Antwort. Sie können nicht auf andere APIs zugreifen, um z. B. die Liste oder die Liste der Kanäle in einem Team abzurufen.

Erstellen ausgehender Webhooks

Erstellen Sie ausgehende Webhooks, und fügen Sie Benutzerdefinierte Bots zu Teams hinzu. Folgen Sie diesen Schritten, um einen ausgehenden Webhook zu erstellen:

1. Wählen Sie im linken Bereich Teams aus.

   

2. Wählen Sie auf der Seite Teams das erforderliche Team aus, um einen ausgehenden Webhook zu erstellen, und wählen Sie ••• aus.

3. Wählen Sie im Dropdownmenü Team verwalten aus.

   

4. Wählen Sie auf der Kanalseite Apps aus.

   

5. Wählen Sie Ausgehenden Webhook erstellen aus.

   

6. Geben Sie auf der Seite Ausgehenden Webhook erstellen die folgenden Details ein:

   • Name: Der Webhooktitel und @mention Registerkarte.
   • Rückruf-URL: Der HTTPS-Endpunkt, der JSON-Nutzlasten akzeptiert und POST-Anforderungen von Teams empfängt.
   • Beschreibung: Eine detaillierte Zeichenfolge, die auf der Profilkarte und im App-Dashboard auf Teamebene angezeigt wird.
   • Profilbild: Ein App-Symbol für Ihren Webhook, das optional ist.

7. Wählen Sie Erstellen aus. Der ausgehende Webhook wird dem Kanal des Teams hinzugefügt.

   

Ein Dialogfeld hashbasierter Nachrichtenauthentifizierungscode (HMAC) wird angezeigt. Es handelt sich um ein Sicherheitstoken, das zum Authentifizieren von Aufrufen zwischen Teams und dem angegebenen externen Dienst verwendet wird. Das HMAC-Sicherheitstoken läuft nicht ab und ist für jede Konfiguration eindeutig.

Hinweis

Der ausgehende Webhook steht den Benutzern des Teams nur zur Verfügung, wenn die URL gültig ist und die Server- und Clientauthentifizierungstoken gleich sind. Beispielsweise ein HMAC-Handshake.

Das folgende Szenario enthält die Details zum Hinzufügen eines ausgehenden Webhooks:

• Szenario: Pushen von Änderungsstatusbenachrichtigungen auf einem Teams-Kanaldatenbankserver an Ihre App.
• Beispiel: Sie verfügen über eine benutzerdefinierte App, die für Ihre Organisation (LOB-App) erstellt wurde, die alle CRUD-Vorgänge (Erstellen, Lesen, Aktualisieren und Löschen) nachverfolgt. Diese Vorgänge werden von Teams-Kanal-HR-Benutzern in einem Microsoft 365-Mandanten an die Mitarbeiterdatensätze vorgenommen.

JSON-Nutzlast der URL

erstellen Sie eine URL auf dem Server Ihrer App, um eine POST-Anforderung mit einer JSON-Nutzlast zu akzeptieren und zu verarbeiten

Ihr Dienst empfängt Nachrichten in einem standardmäßigen Azure Bot Service-Messagingschema. Der Bot Framework-Connector ist ein RESTful-Dienst, der es ermöglicht, den Austausch von Nachrichten im JSON-Format über HTTPS-Protokolle zu verarbeiten, wie in der Azure Bot Service-API dokumentiert. Alternativ können Sie dem Microsoft Bot Framework SDK folgen, um Nachrichten zu verarbeiten und zu analysieren. Weitere Informationen finden Sie unter Übersicht über Azure Bot Service.

Ausgehende Webhooks sind auf die team-Ebene beschränkt und für alle Teammitglieder sichtbar. Benutzer müssen den Namen des ausgehenden Webhooks @mention , um ihn im Kanal aufzurufen.

HMAC-Token überprüfen

Erstellen einer Methode zum Überprüfen des HMAC-Tokens für ausgehenden Webhook

Beispiel für eingehende Nachricht und ID: "contoso" von SigningKeyDictionary von {"contoso", "vqF0En+Z0ucuRTM/01o2GuhMH3hKKk/N2bOmlM31zaA=" }.

Verwenden Sie den Wert "HMAC 03TCao0i55H1eVKUusZOTZRjtvYTs+mO41mPL+R1e1U=" in der Autorisierung des Anforderungsheaders.

Um sicherzustellen, dass Ihr Dienst nur Anrufe von tatsächlichen Teams-Clients empfängt, stellt Teams einen HMAC-Code im HTTP-hmac-Autorisierungsheader bereit. Schließen Sie den Code immer in Ihr Authentifizierungsprotokoll ein.

Ihr Code muss die in der Anforderung enthaltene HMAC-Signatur immer wie folgt überprüfen:

• Generieren Sie das HMAC-Token aus dem Anforderungstext der Nachricht. Es gibt Standardbibliotheken, um dies auf den meisten Plattformen zu tun, z. B . Crypto für Node.js und Teams-Webhookbeispiel für C#. Microsoft Teams verwendet SHA256 HMAC-Standardkryptografie. Sie müssen den Text in ein Bytearray in UTF8 konvertieren.
• Berechnen Sie den Hash aus dem Bytearray des Sicherheitstokens, das von Teams bereitgestellt wird, wenn Sie den ausgehenden Webhook im Teams-Client registriert haben. Weitere Informationen finden Sie unter Erstellen eines ausgehenden Webhooks.
• Konvertieren Sie den Hash mithilfe der UTF-8-Codierung in eine Zeichenfolge.
• Vergleichen Sie den Zeichenfolgenwert des generierten Hashs mit dem in der HTTP-Anforderung angegebenen Wert.

Beispielcodereferenz

public static AuthResponse Validate(AuthenticationHeaderValue authenticationHeaderValue, string messageContent, string claimedSenderId)
{
    //...
    string providedHmacValue = authenticationHeaderValue.Parameter;
    string calculatedHmacValue = null;
    try
    {
        byte[] serializedPayloadBytes = Encoding.UTF8.GetBytes(messageContent);
 
        byte[] keyBytes = Convert.FromBase64String(signingKey);
        using (HMACSHA256 hmacSHA256 = new HMACSHA256(keyBytes))
        {
            byte[] hashBytes = hmacSHA256.ComputeHash(serializedPayloadBytes);
            calculatedHmacValue = Convert.ToBase64String(hashBytes);
        }
 
        if (string.Equals(providedHmacValue, calculatedHmacValue))
        {
            return new AuthResponse(true, null);
        }
        else
        {
            string errorMessage = string.Format(
                "AuthHeaderValueMismatch. Expected:'{0}' Provided:'{1}'",
                calculatedHmacValue,
                providedHmacValue);
 
            return new AuthResponse(false, errorMessage);
        }
    }
    catch (Exception ex)
    {
        Trace.TraceError("Exception occcured while verifying HMAC on the incoming request. Exception: {0}", ex);
        return new AuthResponse(false, "Exception thrown while verifying MAC on incoming request.");
    }
}

Antwortmethode

Erstellen einer Methode zum Senden einer Erfolgs- oder Fehlerantwort

Antworten von ausgehenden Webhooks werden in derselben Antwortkette wie die ursprüngliche Nachricht angezeigt. Wenn der Benutzer eine Abfrage durchführt, gibt Teams eine synchrone HTTP-Anforderung an Ihren Dienst aus, und Ihr Code erhält fünf Sekunden Zeit, um auf die Nachricht zu antworten, bevor die Verbindung abläuft und beendet wird.

Beispielantwort

{
    "type": "message",
    "text": "This is a reply!"
}

Verwenden von adaptiven Karten mit ausgehenden Webhooks

Sie können mit einem ausgehendem Webhook adaptive Karten, Herokarten und SMS als Anlage senden. Karten unterstützen die Formatierung. Weitere Informationen finden Sie unter Formatieren von Karten mit Markdown. Adaptive Karte in ausgehenden Webhooks unterstützt nur openURL Kartenaktionen.

Die folgenden Codes sind Beispiele für eine adaptive Kartenantwort:

C#/.NET

Beispielcodereferenz

// This method is to read the request body content
string content;
using (var reader = new StreamReader(Request.Body))
    {
        content = await reader.ReadToEndAsync();
    }

var Card = new AdaptiveCard(new AdaptiveSchemaVersion("1.4"))
{
    Body = new List<AdaptiveElement>()
    {
        new AdaptiveTextBlock(){Text= $"Request sent by: {incomingActivity.From.Name}"},
        new AdaptiveImage(){Url=new Uri("https://c.s-microsoft.com/en-us/CMSImages/DesktopContent-04_UPDATED.png?version=43c80870-99dd-7fb1-48c0-59aced085ab6")},
        new AdaptiveTextBlock(){Text="Sample image for Adaptive Card.."}
    }
};

var attachment = new Attachment()
{
    ContentType = AdaptiveCard.ContentType,
    Content = Card
};

var sampleResponseActivity = new Activity
{
    Attachments = new [] { attachment }
};

return sampleResponseActivity;

JavaScript/Node.js

Beispielcodereferenz

var receivedMsg = JSON.parse(payload);
var responseMsg = JSON.stringify({
    "type": "message",
    "attachments": [
        {
            "contentType": "application/vnd.microsoft.card.adaptive",
            "contentUrl": null,
            "content": {
                "type": "AdaptiveCard",
                "version": "1.4",
                "body": [
                    {
                        "type": "TextBlock",
                        "text": "Request sent by: " + receivedMsg.from.name
                    },
                    {
                        "type": "Image",
                        "url": "https://c.s-microsoft.com/en-us/CMSImages/DesktopContent-04_UPDATED.png?version=43c80870-99dd-7fb1-48c0-59aced085ab6"
                    },
                    {
                        "type": "TextBlock",
                        "text": "Sample image for Adaptive Card."
                    }
                ]
            },
            "name": null,
            "thumbnailUrl": null
        }
    ]
});

JSON

{
 "type": "message",
 "attachments": [
  {
   "contentType": "application/vnd.microsoft.card.adaptive",
   "content": {
    "type": "AdaptiveCard",
    "version": "1.4",
    "body": [
     {
      "type": "TextBlock",
      "text": "Request sent by: Megan"
     },
     {
      "type": "Image",
      "url": "https://c.s-microsoft.com/en-us/CMSImages/DesktopContent-04_UPDATED.png?version=43c80870-99dd-7fb1-48c0-59aced085ab6"
     },
     {
      "type": "TextBlock",
      "text": "Sample image for Adaptive Card.."
     }
    ]
   }
  }
 ]
}

Codebeispiel

Beispielname	Beschreibung	.NET	Node.js
Ausgehende Webhooks	In diesem Beispiel wird gezeigt, wie ausgehender Webhook implementiert und verwendet wird.	View	View

Schrittweise Anleitung

Befolgen Sie die Schritt-für-Schritt-Anleitung, um ausgehende Webhooks in Teams zu erstellen.

Siehe auch

• Webhooks und Connectors
• Nachrichten erstellen und senden
• Erstellen eingehender Webhooks
• Erstellen von Connectors für Microsoft 365-Gruppen
• Adaptive Karten