Webhooks

In diesem Bereich kann festgelegt werden, ob signoSign/2 beim Eintritt bestimmter Ereignisse (Events) einen “Webhook” versendet.

Für signoSign/2 ist ein Webhook ein HTTP-Request, der von signoSign/2 an eine bestimmte URL gesendet wird. Dieser Request enthält im Body ein JSON-Objekt mit Informationen zum eingetretenen Event, dem Benutzer sowie dem Dokument. Die empfangende Anwendung kann auf diesen Webhook reagieren.

Der Webhook ist besonders nützlich bei Kombination mit einer Webanwendung, z. B. über das URL-Schema, sodass die Webanwendung über den Abschluss des Dokuments informiert wird.

signoSign/2 sendet den Webhook einmalig und erwartet bzw. reagiert nicht auf eine Antwort. Der Webhook dient lediglich zur einseitigen Kommunikation mit einem Drittsystem, um Informationen zu einem Event bereitzustellen.

Allgemein

Im Bereich “Allgemein” wird definiert, zu welchen Events der Webhook versendet werden soll.

Es stehen folgende Events zur Verfügung:

Option	Beschreibung
Archivierung erfolgreich	Definiert eine URL, an die ein Webhook versendet wird, wenn das Dokument erfolgreich archiviert wurde.
Archivierung nicht erfolgreich	Definiert eine URL, an die ein Webhook versendet wird, wenn das Dokument nicht archiviert werden konnte. Dieser Webhook wird nur versendet, wenn es zu einem dauerhaften (“harten”) Fehler kommt, z. B. weil der Archivierungspfad nicht verfügbar ist. Bei einem “weichen” Fehler, wenn z. B. nicht alle Pflichtsignaturen geleistet wurden, wird kein Webhook versendet.
Schließen ohne Archivierung	Definiert eine URL, an die ein Webhook versendet wird, wenn das Dokument geschlossen wurde, ohne es zu archivieren.

Sollte signoSign/2 unerwartet beendet werden, wird kein Webhook versendet.

Beispiel Webhook

Nachfolgendes Beispiel zeigt das JSON-Objekt eines Webhooks, der bei erfolgreicher Archivierung versendet wird:

JSON

{
    "Event": {
        "TimeStamp": "2024-04-11T11:51:37.8801444+02:00",
        "EventType": "ArchivingSucceeded",
        "EventCode": 100,
        "Software": {
            "Name": "signotec signoSign/2",
            "Version": "11.8.1"
        },
        "User": {
            "UserName": "example.user",
            "MachineName": "EXAMPLE-PC"
        },
        "EventData": {
            "Document": {
                "DocumentName": "Test.pdf",
                "DocumentType": "Test",
                "SignatureFields": 2,
                "MandatoryFields": 1,
                "SignedSignatureFields": 1,
                "SignedMandatoryFields": 1
            },
            "Placeholder": [
                {
                    "Name": "Variable1",
                    "Label": "Name",
                    "Value": "Example Name"
                },
                {
                    "Name": "Variable2",
                    "Label": "Phone Number",
                    "Value": "+49 1234567890"
                }
            ]
        }
    }
}