Webhooks

Este servicio será el encargado de notificarte cuando se esté procesando o cuando se complete una sesión de validación de identidad.

Proceso de verificación de la firma digital del request

Junto con la notificación, enviaremos un conjunto de headers HTTP que te servirán para verificar su autenticidad.

Los headers HTTP que enviamos son:

  • X-Api-Key : este header te permitirá identificar qué api-secret tenés que usar en el caso que se hayan configurado múltiples pares de api-key y api-secret.

  • X-Signature : este header contiene la firma digital (timestamp + endpoint + body) que deberás verificar para asegurar la integridad del request. Si la firma no coincide, deberás rechazar el pedido.

  • X-Timestamp : este header contiene el momento en el que se firmó el pedido en formato unix-epoch para que puedas corroborar que la firma no expiró.

  • X-Endpoint : el endpoint al que se realiza el pedido y usaste para generar la firma. Usa este header para regenerar la firma a validar, compararlo con el endpoint de tu servicio y verificar que coinciden.

La firma digital es un código HMAC-SHA256 que se construye usando el api-secret y una serie de bytes que contienen la concatenación del timestamp, endpoint y request body codificados en UTF-8.

El siguiente es un pseudo-código para verificar que la firma digital de un request sea legítima:

requestSignature = request.headers['x-signature']

signatureData = encode(request.headers['x-timestamp'] + request.headers['x-endpoint'] + request.body , 'UTF-8')

clientApiSecretDecoded = base64.b64decode(apiSecret)

recreatedSignature = hmac(clientApiSecretDecoded, signatureData, 'SHA256')

validSignature = requestSignature == 'hmac-sha256 ' + recreatedSignature

Notificaciones de sesión de validación

Deberás indicarnos este endpoint para recibir las notificaciones de una sesión de validación de identidad. Nos deberás devolver un código HTTP del tipo 2xx para que no volvamos a enviar la notificación. Caso contrario, volveremos a enviarla.

Parámetros disponibles
Header Parameters
X-Api-Keystringrequired
Este header te permitirá identificar qué api-secret tenés que usar en el caso que se hayan configurado múltiples pares de api-key y api-secret.
Ejemplo: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
Este header contiene la firma digital (timestamp + endpoint + body) que deberás verificar para asegurar la integridad del request. Si la firma no coincide, deberás rechazar el pedido.
Ejemplo: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
X-Timestampstringrequired
Este header contiene el momento en el que se firmó el pedido en formato unix-epoch para que puedas corroborar que la firma no expiró.
Ejemplo: X-Timestamp: 1637117179
X-Endpointstringrequired
El endpoint al que se realiza el pedido y usaste para generar la firma. Usa este header para regenerar la firma a validar, compararlo con el endpoint de tu servicio y verificar que coinciden.
Ejemplo: X-Endpoint: /client/api/session/completed
Body Parameters
event_idstringrequired
Identificador de evento.
Ejemplo: identity-session-status-changed
Enum: identity-session-status-changed
idempotency_keystringrequired
Identificador idempotente de creación del evento.
Ejemplo: 27Ky00tAZ0Rdi7G2Vt9iino8AYs
sessionobjectrequired
Sesión de validación de identidad

¿Te resultó útil esta sección?

POST/identity/v1/<session-event-client-url>
{
"event_id":
"identity-session-status-changed"
"idempotency_key":
"27Ky00tAZ0Rdi7G2Vt9iino8AYs"
"session":{
"id":
"iss-27KxRhP9YB4ouoyt6a5vVJlY9fR"
"status":
"VERIFIED"
}
}
Ejemplo de respuestas

Notificación de archivo requerido

Deberás indicarnos este endpoint para recibir notificaciones de archivos requeridos. Nos deberás devolver un código HTTP del tipo 2xx para que no volvamos a enviar la notificación. Caso contrario, volveremos a enviarla.

Parámetros disponibles
Header Parameters
X-Api-Keystringrequired
Este header te permitirá identificar qué api-secret tenés que usar en el caso que se hayan configurado múltiples pares de api-key y api-secret.
Ejemplo: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
Este header contiene la firma digital (timestamp + endpoint + body) que deberás verificar para asegurar la integridad del request. Si la firma no coincide, deberás rechazar el pedido.
Ejemplo: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
X-Timestampstringrequired
Este header contiene el momento en el que se firmó el pedido en formato unix-epoch para que puedas corroborar que la firma no expiró.
Ejemplo: X-Timestamp: 1637117179
X-Endpointstringrequired
El endpoint al que se realiza el pedido y usaste para generar la firma. Usa este header para regenerar la firma a validar, compararlo con el endpoint de tu servicio y verificar que coinciden.
Ejemplo: X-Endpoint: /client/api/session/completed
Body Parameters
event_idstringrequired
Identificador de evento.
Ejemplo: identity-required-file
Enum: identity-required-file
idempotency_keystringrequired
Identificador idempotente de creación del evento.
Ejemplo: 27Ky00tAZ0Rdi7G2Vt9iino8AYs
sessionobjectrequired
Sesión de validación de identidad
actionobjectrequired
Acción requerida

¿Te resultó útil esta sección?

POST/identity/v1/<required-file-event-client-url>
{
"event_id":
"identity-required-file"
"idempotency_key":
"27Ky00tAZ0Rdi7G2Vt9iino8AYs"
"session":{
"id":
"iss-27KxRhP9YB4ouoyt6a5vVJlY9fR"
}
"action":{
"file_type":
"company-document"
"reason":
"Falta carta de representación legal"
"requested_at":
"2023-02-09T13:20:32.593Z"
}
}
Ejemplo de respuestas