Webhook-Benachrichtigungen ermöglichen es Sign In App, eine Benachrichtigung an externe Anwendungen zu senden, wenn ein Besucher oder Mitarbeiter sich an- oder abmeldet. Webhooks werden innerhalb der Benachrichtigungen konfiguriert, so dass Sie verschiedene Regeln pro Standort oder Besuchergruppe festlegen können. Erweiterte Filter ermöglichen es Ihnen, Ihren eigenen Arbeitsablauf zu erstellen und verschiedene Webhook-Benachrichtigungen basierend auf den von Ihren Besuchern bereitgestellten Daten zu senden.
Warnung:
Webhook- Veranstaltungen werden nicht für automatische Abmeldungen ausgegeben. Wenn das System z. B. so konfiguriert ist, dass alle Besucher um Mitternacht abgemeldet werden, wird nicht für jeden einzelnen ein Webhook-Veranstaltung ausgegeben.
Wenn Webhooks in einem Datensynchronisationsszenario verwendet werden, ist die beste Option die Verwendung des History Endpoints.
> curl -d '{...}' -X POST https://your.url/
Konfiguration
Die Erstellung einer Benachrichtigung erfolgt über das Portal unter Verwalten > Benachrichtigungen . Fügen Sie eine neue Benachrichtigung hinzu und wählen Sie Webhook als Kanal. Die Voraussetzungen für einen Webhook ist der Endpoint-URL und ein geheimer Schlüssel für die Signatur des Webhooks.
Weitere Informationen über die Konfiguration von Benachrichtigungen finden Sie in Group-notifications.
Anfrage
Unterstützte Ereignisse: Die derzeit von Webhooks unterstützten Ereignisse sind visitor.signin, visitor.signout.
Schema
Key | Type | Description |
|
| Veranstaltungsname |
|
| Datum der Veranstaltung (ISO8601-Format) |
|
| Datum, an dem die Veranstaltung gesendet wurde (ISO8601-Format) |
|
| Einziger Schlüssel der Veranstaltung |
|
| Besucherseite, an der die Veranstaltung stattfand |
|
| Der Besucher, für den die Veranstaltung stattgefunden hat |
Standort Objekt
Key | Typ | Description |
|
| Einziger Bezeichner für den Standort |
|
| Der Typ des Standorts, kann |
|
| Der Name des Standorts |
|
| Die Zeitzone des Standorts |
Besucherobjekt
Key | Typ | Description |
|
| Eindeutiger Identifikator des Besuchers |
|
| Eindeutiger Identifikator des zurückkehrenden Besuchers, falls definiert |
|
| Name des Besuchers |
|
| URL zu einem Bild vom Foto des Besuchers (optional) |
|
| URL zu einem Bild des Besucherausweises (optional) |
|
| Zusätzliche Daten, die über den Besucher erfasst werden |
|
| Persönliche Felder, die mit dem (wiederkehrenden) Besucher verbunden sind |
|
| Wenn der Besucher ein bekannter wiederkehrender Besucher ist |
|
| Wenn der Besucher ein zuvor registrierter Besucher ist |
|
| Wenn der Besucher als remote betrachtet wurde. |
Zusätzliche und persönliche Felder
Zusätzliche und persönliche Felder sind Objects mit Schlüsselwerten.
{
"field1": "value1",
"field2": 789,
"field3": true
}
Beispiel
Ein Beispiel für die Datenformatierung ist unten dargestellt. Ein typischer Abfragetext würde keine neuen Zeilen oder zusätzliche Leerzeichen enthalten.
{
"event": "visitor.signin",
"event_at": "2020-01-01T12:00:01Z",
"pushed_at": "2020-01-01T12:00:01Z",
"idempotency_key": "4EPAoqR4N8jZktby",
"site": {
"id": 4567,
"type": "standard",
"name": "Acme Co",
"timezone": "Europe/London"
},
"visitor": {
"id": 1234,
"name": "John Smith",
"photo_url": null,
"badge_url": null,
"additional": {
"Company": "Acme Ltd",
"Email Address": "[email protected]"
},
"personal_fields": {
"role": "Director",
"Car Reg": "ABC 123"
},
"is_returning": false,
"is_pre_registered": false,
"is_remote": false
},
"visiting": {
"id": 8,
"name": "Adele Vance",
"role": "Retail Manager",
"email": "[email protected]",
"mobile": ""
}
}
Antwort
Sign In App wartet auf einen 2xx HTTP Antwortcode, um zu bestätigen, dass die Anfrage erfolgreich war.
Fehler
Wenn der Endpoint mit einem HTTP-Statuscode antwortet, der nicht als erfolgreich angesehen wird, versucht Sign In App es maximal 3 Mal, bevor es aufgibt.
Signatur-Verifizierung
Die Signaturprüfung bietet einen Mechanismus zur Authentifizierung der von der Sign In App gesendeten Anfrage. Dies geschieht durch ein gemeinsames Geheimnis, das beim Einrichten des Webhooks eingegeben wird. Dies ist zwar optional, wird aber empfohlen.
Beispiel
Wenn eine Webhook-Anfrage an die Webhook-Url gestellt wird, enthält sie auch einen HTTP-Header mit dem Namen „x-signinapp-webhook-signature“.
Der Header besteht aus zwei Teilen, die durch ein Komma getrennt sind. Por ejemplo, x-signinapp-webhook-signature: t=1644316744,s1=462fa402e927893dee0bfec09379718a507c883919442de3dcb1504142ceaa5d.
Der Wert t ist ein Zeitstempel, der bestätigt, wann der Webhook gesendet wurde.
Der Wert s1 ist ein sha256 hmac des Timestamps t, der mit dem http-Body verkettet ist.
Python-Beispiel:
hmac.new("MySharedSecret", "timestamp.body", hashlib.sha256).hexdigest()
Ersetzen Sie das gemeinsame Geheimnis, den Zeitstempel und den http-Body. Beachten Sie, dass zwischen dem Zeitstempel und dem http-Body ein Punkt steht.
Prüfen Sie, ob das Ergebnis dieses Aufrufs mit dem Header der Webhook-Anforderung s1 übereinstimmt.
Weitere Code-Beispiele:
Javascript:
const crypto = require('crypto');
crypto
.createHmac('sha256', secret)
.update(timestamp + '.' + payload, 'utf8')
.digest('hex');
PHP:
$header = $request->getHeader('X-SignInApp-Webhook-Signature');
[$timestamp, $signature] = getSignatureParts($header);
hash_equals($signature, hash_hmac("sha256", "{$timestamp}.{$jsonEncodedPayload}", $secret));
Java:
String signedPayload = String.format("%d.%s", timestamp, payload);
String expectedSignature = Util.computeHmacSha256(secret, signedPayload);
Util.secureCompare(expectedSignature, signature)