Webhooks

Webhooks vous permet de mieux intégrer votre automatisation UiPath à votre ensemble d'applications. Vous pouvez vous inscrire aux événements Orchestrator et les envoyer à n'importe quelle solution externe de DCM, BPM ou CRM et informer différents utilisateurs, par exemple, qu'un nouvel élément de la file d'attente peut être traité, qu'un déclencheur a échoué ou qu'un processus a été mis à jour.

Les Webhooks permettent aux systèmes externes de s'abonner aux différents types d'événements Orchestrator et de les écouter. La page Webhooks (Webhooks) permet de les configurer facilement et d'afficher ceux auparavant créés. Vous pouvez également désactiver des Webhooks, rechercher un spécifique, les modifier ou les supprimer.

Les événements sont disponibles pour les tâches, les robots, les files d'attente, les éléments de file d'attente et les déclencheurs.

Chaque événement envoie une charge utile à une URL spécifiée contenant des informations. Certaines propriétés sont communes à tous, tandis que d'autres sont spécifiques à chaque type d'événement.

Les événements Webhook sont créés par dossier : ainsi, lorsqu’un événement Webhook est associé à une ressource partagée entre plusieurs dossiers telle qu’une file d’attente, un événement Webhook distinct sera généré pour chacun de ces dossiers.

Si la demande de transfert d'un événement échoue, le déclencheur de ce Webhook s'ouvre, désactivant le Webhook pendant une heure.

Remarque :

• Tous les événements Webhook qui auraient dû être envoyés alors que le déclencheur est ouvert sont ignorés et ne sont pas réessayés une fois le déclencheur fermé.
• Les événements Webhook ne sont pas stockés et ne peuvent pas être réessayés ou exportés. Par ailleurs, si l'appel à la plateforme externe échoue, l'événement est perdu. Les webhooks sont conçus pour un traitement en temps réel.

Propriétés de charges utiles communes

Nom de la propriété	Type de propriété	Description et exemple
Saisie de texte	string	Le type d'événement qui a déclenché la notification. Cette propriété s'affiche pour tous les types d'événements. Exemple : "Type": "job.created" "Type":"process.updated"
EventID	string	Un identificateur généré de façon unique pour chaque événement lorsqu'il se produit. Cette propriété s'affiche pour tous les types d'événements. Exemple : "EventId":"3e5af0113e674ae597c579cb35ed8630"
Horodatage	Date RFC 8601	La date et heure de génération de l'événement. Cette propriété s'affiche pour tous les types d'événements. Exemple : "Timestamp":"2018-11-02T11:47:48.5790797Z"
TenantId	Integer	L'ID du locataire sur lequel l'événement a été généré. Le locataire par défaut est 1. Cette propriété s'affiche pour tous les types d'événements. Exemple : "TenantId":3
UserId	Integer	L'ID utilisateur dont l'action a déclenché l'événement. Ce paramètre ne s'affiche pas si l'événement est déclenché par un robot ou un déclencheur. Cette propriété s'affiche pour tous les types d'événements. Exemple : "UserId": 4947
FolderID	Integer	L’ID du dossier dans lequel l’événement a été généré. Ce paramètre ne s'affiche pas pour les événements déclenchés des robots modernes. Exemple : "FolderId": 26

Autorisations

Pour pouvoir effectuer diverses opérations sur la page Webhooks (Webhooks), les autorisations correspondantes doivent vous être accordées sur les Webhooks :

• Consultation (View) : permet de consulter les Webhooks et leurs détails, ainsi que les récupérer à l'aide de l'API, envoyer une requête de ping ou obtenir la liste de tous les événements auxquels un Webhook peut s'abonner.
• Création (Create) : cette autorisation permet d'ajouter des Webhooks. Notez que vous avez également besoin des autorisations de Consultation (View).
• Modifier (Edit) - vous accorde le droit de modifier les webhooks à partir de l'interface utilisateur ou en utilisant l'API. Notez que vous avez également besoin des autorisations Consultation (View).
• Suppression (Delete) : autorisation qui permet de supprimer les Webhooks. Notez que vous avez également besoin des autorisations de Consultation (View).

Authentification

Toutes les requêtes HTTP du Webhook utilisent la clé secrète que vous ajoutez lorsque vous créez un Webhook pour vous authentifier. Elle est combinée au corps de la requête utilisant un hachage à clé HMAC-SHA256. Cela entraîne une signature sécurisée qui ne contient pas d'informations sur la clé secrète, qui est unique à chaque requête et qui est envoyée via l'en-tête HTTP X-UiPath-Signature.

Les applis clientes qui reçoivent des requêtes d'Orchestrator doivent vérifier l'authenticité des requêtes. La signature de la requête suit le modèle suivant :

• L'appli cliente reçoit une requête du Webhook d'Orchestrator ;
• L'appli cliente calcule une signature en fonction de la requête ;

• L'appli cliente tente de faire correspondre la signature qu'il a calculée avec la signature de la requête :

  • Si les signatures ne correspondent pas, l'appli cliente ne doit pas traiter la requête.
  • Si elles correspondent, la requête doit être traitée.

Le calcul de la signature doit être effectué comme suit :

1. Récupérez l'en-tête HTTP X-UiPath-Signature.
2. Pour obtenir des octets de signature bruts, décodez la valeur de l'en-tête de Base64.

3. Récupérez le corps brut de la requête.

   Remarque : Les requêtes d'Orchestrator sont toujours encodées à l'aide d'UTF-8.
4. Calculez le hachage à l'aide de SHA256 et de la clé de signature (encodé en UTF-8).
5. Comparez la signature calculée avec la valeur de l'en-tête HTTP X-UiPath-Signature :
   • Si les signatures ne correspondent pas, ne traitez pas la requête.
   • Si elles correspondent, la requête doit être traitée.

Exemples de validation de signatures

using System;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;
 
 
public async Task<bool> IsValidRequestAsync(HttpRequestMessage request, string secret)
{
    if (!request.Headers.TryGetValues("X-UiPath-Signature", out var headerValues))
        return false;
 
    var orchestratorSignature = Convert.FromBase64String(headerValues.First());
    using (var sha = new HMACSHA256(key: Encoding.UTF8.GetBytes(secret)))
    {
        var computedSignature = sha.ComputeHash(await request.Content.ReadAsByteArrayAsync());
        return ByteArrayEquals(orchestratorSignature, computedSignature);
    }
}

const { createServer } = require('http');
const { createHmac } = require('crypto');
 
const PORT = 9090
const WEBHOOK_SECRET = '<same secret as configured in Orchestrator>'
 
const isValidRequest = (body /* Buffer */, secret /* string */, expectedSignature /* string */) =>
    expectedSignature == null || createHmac('sha256', secret)
        .update(body)
        .digest('base64') === expectedSignature
 
const server = createServer((req, resp) => {
 
    let body = new Buffer([])
 
    req.on('data', chunk => body = Buffer.concat([body, chunk]))
 
    req.on('end', () => {
 
        if (!isValidRequest(body, WEBHOOK_SECRET, req.headers['x-uipath-signature'])) {
            console.error('Invalid signature')
            resp.statusCode = 401 // Unauthorized
        } else {
 
            let payload = JSON.parse(body.toString('utf8'))
 
            // Process request
            console.log(payload)
 
            resp.statusCode = 202 // Accepted
        }
 
        resp.end()
    })
 
})
 
server.listen(PORT)