Webhooks

El sistema de Coremetrix puede notificar a tu backend cuando ocurran ciertos eventos, utilizando webhooks. Puedes suscribirte a eventos en tiempo real a través de los webhooks de Coremetrix. Los webhooks pueden gestionarse a través de la API de Subscriptions.

Esta API se puede utilizar para suscribirse a varios eventos del ciclo de vida del cuestionario.

Cómo funciona:

Eventos admitidos

Actualmente admitimos suscripciones a los siguientes eventos:

Note: La lista completa de eventos a los que puedes suscribirte se puede encontrar llamando al/subscriptions/events endpoint:

Carga del webhook

Cuando creas una suscripción a través de la API de Suscripciones, debes proporcionar una URL. Cuando ocurra cualquiera de los eventos descritos anteriormente, Coremetrix enviará los datos correspondientes mediante POST a la URL proporcionada. Tu API debe ser capaz de consumir la siguiente carga:

{
"event": "quiz_consent",
"consentTime": "2020-01-31T13:14:35.208Z",
"lastUpdated": "2020-01-31T13:14:35.208Z",
"slug": "sandbox",
"puid": "a_puid",
"quizId": "481ac0fe-ac33-402a-9367-2aaa7a98b49d",
"consent": true
}

{
"event": "quiz_consent_withdrawal",
"withdrawalTime": "2020-01-31T13:25:02.786Z",
"lastUpdated": "2020-01-31T13:25:02.786Z",
"slug": "sandbox",
"puid": "a_puid",
"quizId": "481ac0fe-ac33-402a-9367-2aaa7a98b49d",
"consent": false
}

El estado del intento puede ser uno de los siguientes:

{
"event": "attempt_profiled",
"attemptId": "4d1c90d4-f1fe-4303-ad83-535d99a61cf5",
"quizId": "481ac0fe-ac33-402a-9367-2aaa7a98b49d",
"puid": "a_puid",
"age": "age",
"gender": "gender",
"maritalStatus": "maritalStatus",
"occupation": "occupation",
"accommodation": "accommodation",
"education": "education",
"profiles": {
"basic_profile": {
"value": "HIGH",
"scale": [
"LOW",
"MEDIUM",
"HIGH"
]
}
},
"profileFlags": { },
"status": "COMPLETED_SCORED"
}

El estado del intento puede ser uno de los siguientes:

Seguridad

Cifrado de datos durante la transmisión

Coremetrix emplea cifrado para toda la transmisión de datos. La API de Suscripciones solo aceptará el protocolo https. Esto es para proteger la comunicación entre el sistema de Coremetrix y tu backend. Debes activar TLS en tu servidor y configurar la URL de suscripción para que use https.

Autenticación básica HTTP

Coremetrix admite la autenticación básica HTTP para permitir que tu backend asegure la URL del suscriptor. Esto asegurará que solo Coremetrix pueda enviar datos a tu servidor.

La API de Suscripciones te permitirá crear una URL de suscriptor con el siguiente formato: https://username:password@my_server.com/my_secure_path

Note: username and password should not contain any : or @ symbols.

OAuth 2.0

OAuth 2.0 es un estándar abierto para la autorización en internet. Coremetrix admite la autorización OAuth 2.0 para permitir que nuestro backend tenga acceso limitado a tu punto final de webhook.

OAuth 2.0 requiere un token de autenticación, que es emitido por un servidor de autorización.

Para otorgar acceso a Coremetrix para enviar datos a tu punto final de webhook, primero debes configurar tus suscripciones usando la API de Suscripciones.

Para cada suscripción, también debes proporcionar la siguiente configuración:

Note: Estos parámetros se agregarán utilizando el formato application/x-www-form-urlencoded con una codificación de caracteres UTF-8 en el cuerpo de la entidad de la solicitud HTTP.

Puedes encontrar detalles completos aquí.

Cómo funciona:

Flujo de credenciales del cliente

OAuth 2.0 especifica múltiples flujos para obtener y validar tokens. Coremetrix admite el Flujo de Credenciales del Cliente, donde la comunicación es estrictamente de servidor a servidor. No se emite un Token de Actualización en este flujo, ya que el cliente puede recuperar un nuevo Token de Acceso usando sus credenciales de todos modos.

Cuando ocurre un evento, si OAuth 2.0 está configurado:

1. Para obtener un Token de Acceso, Coremetrix llamará a tu servidor OAuth pasando la credencial (previamente registrada a través de la API de Suscripciones). El token de acceso se utilizará al enviar datos al webhook.

Tokens Web JSON

Los Tokens Web JSON te permiten verificar que los datos enviados a tu servidor no han sido manipulados y que realmente provienen de Coremetrix.

Cómo funciona:

1. Coremetrix incluirá todos los datos de eventos en la carga útil del token JWT.
2. Para evitar ataques de repetición, , Coremetrix incluirá un nonce (jti reclamo), el tiempo de creación (iat reclamo) y un tiempo de expiración (exp reclamo) como parte de la carga útil del JWT. El tiempo de expiración está configurado actualmente en 60 segundos.
3. Coremetrix firma el token JWT utilizando HS512 y tu clave de API secreta en el formato “{apiKey}+{apiKey}”.
4. Coremetrix enviará este token en un encabezado llamado X-Coremetrix-Signature al enviar datos a tu servidor.

Validación del JWT:

Deberás validar el JWT para verificar su autenticidad. Puedes hacer esto verificando su firma digital y sus reclamos. Hay varias bibliotecas disponibles para ayudarte en esto. Por ejemplo, puedes usar la biblioteca jjwt para Java.

Reintentos y retroceso exponencial

Coremetrix volverá a intentar enviar los eventos en caso de error. Además de los reintentos, Coremetrix implementa el algoritmo de retroceso exponencial para lograr un mejor control del flujo. En caso de error devuelto por tu servidor al intentar entregar los eventos, el sistema de Coremetrix volverá a intentarlo después de un período de tiempo. El tiempo de espera aumentará incrementalmente entre las solicitudes de reintentos consecutivos después de cada falla. Esto dará a tu servicio suficiente tiempo para recuperarse

Coremetrix volverá a intentar enviar mensajes a tu sistema durante aproximadamente 1 hora. Si tu servicio está inactivo durante más de una hora, te recomendamos que utilices la API de informes de Coremetrix para obtener la información faltante.