Webhooks

Mit Webhooks können Sie Ihre UiPath®-Automatisierung besser in Ihre gesamtes Anwendungsumgebung 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 ermöglichen es externen Systemen, verschiedene Typen von Orchestrator-Ereignissenzu abonnieren und zu empfangen. Auf der Seite Webhooks können Sie sie einfach einrichten und die bereits erstellten anzeigen. Sie können auch Webhooks deaktivieren, nach einem bestimmten suchen, sie bearbeiten oder löschen.

Ereignisse stehen für Aufträge, Roboter, Warteschlangen, Warteschlangenobjekte, Prozesse und Trigger zur Verfügung. Die vollständige Liste der Ereignisse und einige Beispiele finden Sie auf dieser Seite.

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.

Webhook-Ereignisse werden ordnerweise erstellt. Wenn Sie also ein Webhook-Ereignis einer Ressource zugeordnet haben, die von Ordnern gemeinsam genutzt wird, z. B. eine Warteschlange, wird für jeden dieser Ordner ein separates Webhook-Ereignis generiert.

Wenn die Anforderung zur Weiterleitung eines Ereignisses fehlschlägt, wird der Leistungsschalter für den jeweiligen Webhook geöffnet und der Webhook für eine Stunde deaktiviert.

Hinweis:

• Alle Webhook-Ereignisse, welche bei offenem Schutzschalter hätten gesendet werden sollen, werden übersprungen und nicht erneut gesendet, sobald der Schutzschalter geschlossen ist.
• Webhook-Ereignisse werden nicht gespeichert und können nicht wiederholt oder exportiert werden. Wenn der Aufruf der externen Plattform fehlschlägt, geht das Ereignis außerdem verloren. Webhooks sind für die Echtzeitverarbeitung konzipiert.

Häufige Eigenschaften von Nutzdaten

Name der Eigenschaft	Eigenschaftstyp	Beschreibung und Beispiel
Name	string	Der Name des Webhooks. Diese Eigenschaft wird für alle Ereignistypen angezeigt und ist obligatorisch. Beispiel: "Name":"update.event"
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

Berechtigungen

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

• Ansicht (View) - Ermöglicht Ihnen, Webhooks und deren Details anzuzeigen, sie mit der API abzurufen, eine Ping-Anforderung zu senden oder die Liste aller Ereignisse abzurufen, die ein Webhook abonnieren kann.
• Erstellen (Create) - Diese Berechtigung ermöglicht Ihnen, neue Webhooks hinzuzufügen. Bitte beachten Sie, dass Sie auch Anzeige-Berechtigungen brauchen.
• Bearbeiten (Edit) - Erteilt Ihnen die Berechtigung, Webhooks über die Bedienoberfläche oder mit der API zu bearbeiten. Bitte beachten Sie, dass Sie auch Anzeige-Berechtigungen brauchen.
• 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 den Geheimschlüssel, den Sie hinzufügen, wenn Sie einen Webhook zum Authentifizieren erstellen. Er wird mit einem HMAC-SHA256 Keyed-Hash mit dem Anforderungstext 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)