Sign In App Documentation
Webhooks
Les notifications Webhook permettent à Sign In App d'envoyer une alerte à des applications externes lorsqu'un visiteur ou un membre du personnel enregistre son entrée ou sortie. Les webhooks sont configurés dans les notifications, de sorte que des règles différentes peuvent être définies par site ou par groupe de visiteurs. Les filtres avancés vous permettent de construire votre propre flux de travail, en envoyant différentes notifications webhook basées sur les données fournies par vos visiteurs.
Avertissement
Les événements Webhook ne sont pas émis pour la fonctionnalité d'enregistrement de sortie automatique. Par exemple, si le système est configuré pour que tous les visiteurs enregistrent leur sortie du site à minuit, un événement webhook ne sera pas émis pour chaque individu. Si les webhooks sont utilisés dans un scénario de synchronisation des données, la meilleure option est d'utiliser le endpoint de l'historique.
> curl -d '{...}' -X POST https://your.url/
Configuration
La création d'une notification s'effectue par le biais du portail via Gérer > Notifications. Ajoutez une nouvelle notification et sélectionnez webhook comme canal. Les conditions requises pour un webhook sont le endpoint URL et une clé secrète pour la signature du webhook.
Vous trouverez plus d'informations sur la configuration des notifications dans Notifications de groupe.
Requête
Événements pris en charge
Les événements actuellement supportés par les webhooks sont visitor.signin, visitor.signout.
Schéma
| Key | Type | Description |
|---|---|---|
event | String | Nom de l'événement |
event_at | String | Date de l'événement (format ISO8601) |
pushed_at | String | Date à laquelle l'événement a été poussé (format ISO8601) |
idempotency_key | String | Clé unique pour l'événement |
site | Object | Le site du visiteur sur lequel l'événement s'est produit |
visitor | Object | Le visiteur pour lequel l'événement s'est produit |
Objet du site
| Key | Type | Description |
|---|---|---|
id | Integer | Identifiant unique du site |
type | String | Type de site, qui peut être standard ou distant |
name | String | Nom du site |
timezone | String | Le fuseau horaire du site |
Objet visiteur
| Key | Type | Description |
|---|---|---|
id | Integer | Identificateur unique du visiteur |
returning_visitor_id | Integer | Identifiant unique du visiteur qui revient, s'il a été défini |
name | String | Le nom du visiteur |
photo_url | String | Url vers une image de la photo du visiteur (optionnel) |
badge_url | String | URL d'une image du badge du visiteur ( optionnel) |
additional | Object | Données supplémentaires enregistrées sur le visiteur |
personal_fields | Object | Champs personnels associés au visiteur ( qui revient) |
is_returning | Boolean | Il s'agit d'un visiteur dont on sait qu'il revient sur le site |
is_pre_registered | Boolean | Si le visiteur a été pré-enregistré |
is_remote | Boolean | Si le visiteur a été considéré comme distant |
Champs supplémentaires et personnels
Les champs additionnels et personnels sont des valeurs clés Objects.
{
"field1": "value1",
"field2": 789,
"field3": true
}
Exemple
Voici un exemple formaté des données. Un corps de requête typique ne contiendrait pas de nouvelles lignes ni d'espaces supplémentaires.
{
"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": ""
}
}
Réponse
Sign In App attend un code de réponse 2xx HTTP pour confirmer que la demande a abouti.
Erreurs
Lorsque votre endpoint répond avec un code d'état HTTP qui n'est pas considéré comme un succès, Sign In App continuera à réessayer pendant un maximum de 3 fois avant d'abandonner.
Vérification de la signature
La vérification de la signature fournit un mécanisme permettant d'authentifier la demande envoyée par Sign In App. Pour ce faire, nous disposons d'un code secret partagé, renseigné lors de la mise en place du webhook. Bien que cela soit facultatif, il est recommandé de le faire.
Exemple
Lorsqu'une requête webhook est faite à l'url webhook, elle inclura également un en-tête HTTP avec le nom x-signinapp-webhook-signature.
L'en-tête est composé de deux parties séparées par une virgule. Par exemple, x-signinapp-webhook-signature : t=1644316744,s1=462fa402e927893dee0bfec09379718a507c883919442de3dcb1504142ceaa5d
La valeur t est un horodatage utilisé pour confirmer l'envoi du webhook.
La valeur s1 est un sha256 hmac de l'horodatage de t concaténé avec le corps http.
Exemple Python :
hmac.new("MySharedSecret", "timestamp.body", hashlib.sha256).hexdigest()
Remplacer le secret partagé, l'horodatage et le corps http. Notez qu'il y a un endpoint entre l'horodatage et le corps http.
Vous devez vérifier que le résultat de cet appel correspond à s1 dans l'en-tête de la requête du webhook.
Autres exemples de code :
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)