Webhooks

Mit Webhooks können Sie Ihre UiPath-Automatisierung besser in Ihr gesamtes Anwendungsökosystem integrieren. Sie können Orchestrator-Ereignisse abonnieren und sie an beliebige externe DCM-, BPM- oder CRM-Lösungen senden und verschiedene Benutzer informieren, z. B. dass ein neues Warteschlangenelement verarbeitet werden kann, ein Trigger fehlgeschlagen ist oder ein Prozess aktualisiert wurde.

Webhooks allow external systems to subscribe and listen to different types of Orchestrator events. The Webhooks page enables you to easily set them up, as well as view the ones that have been previously created. You can also disable webhooks, search for a specific one, edit or delete them.

Events are available for jobs, robots, queues, queue items, processes, and triggers. For the full list of event types and a few examples, please check this page.

Jedes Ereignis sendet Nutzdaten mit Informationen an eine angegebene URL. Einige Eigenschaften gelten für alle gemeinsam, während andere jeweils für einen bestimmten Ereignistyp bestimmt sind.

Häufige Eigenschaften von Nutzdaten

Name der Eigenschaft	Eigenschaftstyp	Beschreibung und Beispiel
Typ	string	Der Ereignistyp, der die Benachrichtigung ausgelöst hat. Diese Eigenschaft wird für alle Ereignistypen angezeigt. Beispiel: "Type": "job.created" "Type":"process.updated"
EventID	string	Ein Identifier, der nur beim Auftreten eines bestimmten Ereignisses generiert wird. Diese Eigenschaft wird für alle Ereignistypen angezeigt. Beispiel: "EventId":"3e5af0113e674ae597c579cb35ed8630"
Zeitstempel	RFC 8601-Datum	Das Datum und die Uhrzeit, zu denen das Ereignis generiert wurde. Diese Eigenschaft wird für alle Ereignistypen angezeigt. Beispiel: "Timestamp":"2018-11-02T11:47:48.5790797Z"
TenantId	Integer	Die ID des Mandanten, für den das Ereignis generiert wurde. Der Standardmandant ist 1. Diese Eigenschaft wird für alle Ereignistypen angezeigt. Beispiel: "TenantId":3
UserId	Integer	Die Benutzer-ID, deren Aktion das Ereignis ausgelöst hat. Dieser Parameter wird nicht angezeigt, wenn das Ereignis von einem Roboter oder einem Trigger ausgelöst wird. Diese Eigenschaft wird für alle Ereignistypen angezeigt. Beispiel: "UserId": 4947
FolderID	Integer	Die ID des Ordners, in dem das Ereignis generiert wurde. Dieser Parameter wird nicht für Ereignisse angezeigt, die von modernen Robotern ausgelöst werden. Beispiel: "FolderId": 26

Berechtigungen

Um die verschiedenen Operationen auf der Seite Webhooks durchführen zu können, müssen Ihnen die entsprechenden Berechtigungen erteilt worden sein:

• View - Enables you to view webhooks and their details, as well as retrieve them using the API, send a ping request, or get the list of all the events to which a webhook can subscribe.
• Erstellen (Create) - Diese Berechtigung ermöglicht Ihnen, neue Webhooks hinzuzufügen. Bitte beachten Sie, dass Sie auch Anzeige-Berechtigungen brauchen.
• Edit - Grants you the right to edit webhooks from the UI or by using the API. Please note that you also require View permissions.
• Löschen (Delete) - eine Berechtigung, mit der Sie Webhooks löschen können. Bitte beachten Sie, dass Sie auch Anzeige-Berechtigungen brauchen.

Authentication

Alle Webhook HTTP-Anforderungen verwenden das Geheimnis, das Sie hinzufügen, wenn Sie einen Webhook zum Authentifizieren erstellen. Er wird mit einem HMAC-SHA256 Keyed-Hash mit dem Hauptteil der Anforderung kombiniert. Daraus entsteht eine sichere Signatur, die keine geheimen Informationen enthält, einzigartig für jede Anforderung ist und durch den X-UiPath-Signature HTTP-Header gesendet wird.

Client-Apps, die Orchestrator-Anforderungen erhalten, müssen die Echtheit der Anforderungen überprüfen. Die Anforderungssignatur hat folgendes Muster:

• Die Client-App erhält eine Webhook-Anforderung von Orchestrator.
• Die Client-App berechnet basierend auf der Anforderung eine Signatur.
• Die Client-App versucht, festzustellen, ob die berechnete Signatur mit der Anforderungssignatur übereinstimmt.
  • Stimmen die Signaturen nicht überein, darf die Client-App die Anforderung nicht bearbeiten.
  • Stimmen die Signaturen überein, muss die Client-App die Anforderung bearbeiten.

Berechnung der Signatur:

1. Rufen Sie den HTTP-Header X-UiPath-Signature ab.

2. Um die rohen Signaturbytes zu erhalten, decodieren Sie den Wert des Headers mit Base64.

3. Rufen Sie den rohen Hauptteil der Anforderung ab.

   Hinweis:

   Orchestrator-Anforderungen sind immer mit UTF-8 codiert.

4. Berechnen Sie den Hash mit SHA256 und dem Signaturschlüssel (mit UTF-8 verschlüsselt).

5. Vergleichen Sie die berechnete Signatur mit dem Wert des HTTP-Headers X-UiPath-Signature:

   • Stimmen die Signaturen nicht überein, darf die Anforderung nicht bearbeitet werden.
   • Stimmen die Signaturen überein, muss die Client-App die Anforderung bearbeiten.

Beispiele für Signaturvalidierung

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)