Créer des webhooks sortants

Créer une URL sur le serveur de votre application pour accepter et traiter une demande POST avec une charge utile JSON

Votre service reçoit des messages dans un schéma de messagerie de service de bot Azure standard. Le connecteur Bot Framework est un service RESTful qui permet de traiter l’échange de messages au format JSON via des protocoles HTTPS, comme documenté dans l’API Azure Bot Service. Vous pouvez également suivre le kit de développement logiciel (SDK) Microsoft Bot Framework pour traiter et analyser les messages. Pour plus d’informations, consultez vue d’ensemble d’Azure Bot Service.

Les webhooks sortants sont limités au niveau team et sont visibles par tous les membres de l’équipe. Les utilisateurs doivent @mention le nom du webhook sortant pour l’appeler dans le canal.

Créer une méthode pour vérifier le jeton HMAC du webhook sortant

Utilisation d’un exemple de message entrant et d’ID : « contoso » de SigningKeyDictionary de {"contoso", "vqF0En+Z0ucuRTM/01o2GuhMH3hKKk/N2bOmlM31zaA=" }.

Utilisez la valeur « HMAC 03TCao0i55H1eVKUusZOTZRjtvYTs+mO41mPL+R1e1U= » dans l’autorisation de l’en-tête de demande.

Pour vous assurer que votre service reçoit uniquement les appels de clients Teams réels, Teams fournit un code HMAC dans l’en-tête d’autorisation HTTP hmac . Incluez toujours le code dans votre protocole d’authentification.

Votre code doit toujours valider la signature HMAC incluse dans la demande comme il suit :

• Générer le jeton HMAC à partir du corps de la demande du message. Il existe des bibliothèques standard pour effectuer cette opération sur la plupart des plateformes, telles que Crypto pour Node.js et l’exemple de webhook Teams pour C#. Microsoft Teams utilise le chiffrement HMAC SHA256 standard. Vous devez convertir le corps en un tableau d’octets en UTF8.
• Calculez le hachage à partir du tableau d’octets du jeton de sécurité fourni par Teams lorsque vous avez enregistré le webhook sortant dans le client Teams. Consultez créer un webhook sortant.
• Convertissez le hachage en chaîne à l’aide du codage UTF-8.
• Comparez la valeur de chaîne du hachage généré à la valeur fournie dans la requête HTTP.

Exemple de référence de code

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.");
    }
}

Créer une méthode pour envoyer une réponse de réussite ou d’échec

Les réponses de vos webhooks sortants apparaissent dans la même chaîne de réponse que le message d’origine. Lorsque l’utilisateur effectue une requête, Teams envoie une demande HTTP synchrone à votre service et votre code obtient cinq secondes pour répondre au message avant que la connexion n’arrive à terme et ne se termine.

Exemple de réponse

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

Exemple de référence de code

// 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;

Exemple de référence de code

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
        }
    ]
});

{
 "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.."
     }
    ]
   }
  }
 ]
}