Sign In App Documentation
Webhooks
Las notificaciones Webhook permiten a Sign In App enviar una alerta a aplicaciones externas cuando un visitante o miembro del personal registra entrada o salida. Los webhooks se configuran dentro de las notificaciones, por lo que se pueden establecer diferentes reglas por sitio o grupo de visitantes. Los filtros avanzados le permiten construir su propio flujo de trabajo, enviando diferentes notificaciones webhook basadas en los datos que sus visitantes proporcionan.
Advertencia
Los eventos webhook no se emiten para la funcionalidad de registro de salida automático. Por ejemplo, si el sistema está configurado para registrar salida de todos los visitantes a medianoche, no se emitirá un evento webhook para cada individuo. Si se utilizan webhooks en un escenario de sincronización de datos, la mejor opción es utilizar el endpoint de historial.
> curl -d '{...}' -X POST https://your.url/
Configuración
La creación de una notificación se realiza a través del Portal en Administrar > Notificaciones . Añada una nueva notificación y seleccione webhook como canal. Los requisitos para un webhook son el endpoint URL y una clave secreta para la firma del webhook .
Puede encontrar más información sobre la configuración de Notificaciones en Notificaciones de grupo.
Solicitud
Eventos soportados
Los eventos actualmente soportados por webhooks son visitor.signin, visitor.signout.
Esquema
| Key | Type | Description |
|---|---|---|
event | String | Nombre del evento |
event_at | String | Fecha del evento (formato ISO8601) |
pushed_at | String | Fecha en que se envió el evento (formato ISO8601) |
idempotency_key | String | Clave única del evento |
site | Object | Sitio del visitante en el que se produjo el evento |
visitor | Object | El visitante para el que se ha producido el evento |
Objeto del sitio
| Key | Type | Description |
|---|---|---|
id | Integer | Identificador único del sitio |
type | String | El tipo de sitio, puede ser standard o remote |
name | String | El nombre del sitio |
timezone | String | La zona horaria del sitio |
Objeto Visitante
| Key | Type | Description |
|---|---|---|
id | Integer | Identificador único del visitante |
returning_visitor_id | Integer | Identificador único del visitante que regresa, si está definido |
name | String | Nombre del visitante |
photo_url | String | URL a una imagen de la foto del visitante (opcional) |
badge_url | String | Una URL a una imagen de la insignia del visitante (opcional) |
additional | Object | Datos adicionales registrados sobre el visitante |
personal_fields | Object | Campos personales asociados al visitante (que regresa) |
is_returning | Boolean | Si el visitante es un visitante recurrente conocido |
is_pre_registered | Boolean | Si el visitante se registró previamente |
is_remote | Boolean | Si el visitante fue considerado remoto. |
Campos adicionales y personales
Los campos adicionales y personales son Objects de valor clave.
{
"field1": "value1",
"field2": 789,
"field3": true
}
Ejemplo
A continuación se muestra un ejemplo de formato de los datos. Un cuerpo de solicitud típico no contendría nuevas líneas ni espacios adicionales.
{
"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": ""
}
}
Respuesta
Sign In App espera un código de respuesta 2xx HTTP para confirmar que la solicitud se ha realizado correctamente.
Errores
Si el endpoint responde con un código de estado HTTP que no se considera correcto, Sign In App seguirá intentándolo un máximo de 3 veces antes de darse por vencida.
Verificación de firma
La verificación de firma proporciona un mecanismo para autenticar que la solicitud ha sido enviada por Sign In App. Esto se consigue mediante un código secreto compartido, que se rellena al configurar el webhook. Aunque esto es opcional, se recomienda.
Ejemplo
Cuando se realiza una solicitud webhook a la url webhook, también incluirá una cabecera HTTP con el nombre x-signinapp-webhook-signature.
La cabecera se compone de dos partes separadas por una coma. Por ejemplo, x-signinapp-webhook-signature: t=1644316744,s1=462fa402e927893dee0bfec09379718a507c883919442de3dcb1504142ceaa5d.
El valor t es una marca de tiempo utilizada para confirmar cuándo se envió el webhook.
El valor s1 es un sha256 hmac del timestamp de t concatenado con el cuerpo http.
Ejemplo en Python:
hmac.new("MySharedSecret", "timestamp.body", hashlib.sha256).hexdigest()
Sustituya el secreto compartido, la marca de tiempo y el cuerpo http. Ten en cuenta que hay un punto entre la marca de tiempo y el cuerpo http.
Deberías comprobar que el resultado de esta llamada coincide con s1 en la cabecera de la petición del webhook.
Otros ejemplos de código:
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)