Sign In App Documentation
Webhooks
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.
Gliederung
| Key | Type | Description |
|---|---|---|
event | String | Veranstaltungsname |
event_at | String | Datum der Veranstaltung (ISO8601-Format) |
pushed_at | String | Datum, an dem die Veranstaltung gesendet wurde (ISO8601-Format) |
idempotency_key | String | Einziger Schlüssel der Veranstaltung |
site | Object | Besucherseite, an der die Veranstaltung stattfand |
visitor | Object | Der Besucher, für den die Veranstaltung stattgefunden hat |
Standort Objekt
| Key | Typ | Description |
|---|---|---|
id | Integer | Einziger Bezeichner für den Standort |
type | String | Der Typ des Standorts, kann Standard oder remote sein |
name | String | Der Name des Standorts |
timezone | String | Die Zeitzone des Standorts |
Besucherobjekt
| Key | Typ | Description |
|---|---|---|
id | Integer | Eindeutiger Identifikator des Besuchers |
returning_visitor_id | Integer | Eindeutiger Identifikator des zurückkehrenden Besuchers, falls definiert |
name | String | Name des Besuchers |
photo_url | String | URL zu einem Bild vom Foto des Besuchers (optional) |
badge_url | String | URL zu einem Bild des Besucherausweises (optional) |
additional | Object | Zusätzliche Daten, die über den Besucher erfasst werden |
personal_fields | Object | Persönliche Felder, die mit dem (wiederkehrenden) Besucher verbunden sind |
is_returning | Boolean | Wenn der Besucher ein bekannter wiederkehrender Besucher ist |
is_pre_registered | Boolean | Wenn der Besucher ein zuvor registrierter Besucher ist |
is_remote | Boolean | 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": "john@smith.com"
},
"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": "AdeleV@2064mx.onmicrosoft.com",
"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.
Unterschrift prüfen
Die Unterschriftsprüfung bietet einen Mechanismus zur Authentifizierung, dass die Anfrage von Sign In App gesendet wurde. Dies wird mit Hilfe eines gemeinsamen Geheimcodes erreicht, der bei der Konfiguration des Webhooks eingegeben wird. Obwohl dies optional ist, wird es 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)