Saltar al contenido principal

Webhook

Los artículos de GetProcess de esta documentación describen una forma de obtener el estado de un proceso mediante una llamada a un endpoint. De esta manera, se realiza un polling para recibir información sobre los procesos que se han creado. Esto significa que el endpoint puede llamarse varias veces para el mismo proceso para obtener el estado más reciente.

Con el uso de webhooks, es posible notificar a un endpoint específico cada vez que cambia el estado de un proceso.

¿Qué es un webhook?​

Un webhook es un servicio de notificación sistémica que permite la integración asíncrona entre sistemas, donde un sistema notifica al otro mediante un disparador. De esta forma, los webhooks pueden mantener los sistemas actualizados con la información más reciente sin necesidad de un polling constante para verificar actualizaciones.

Cómo configurar el Webhook​

Para configurar el webhook, se requiere la siguiente información:

  • URL de notificación: Es el endpoint utilizado por Unico para las notificaciones sobre las actualizaciones de estado.
  • Tipo de autenticación: Es el método utilizado para autenticar la invocación del endpoint. Las siguientes opciones están disponibles:
    • OAuth2;
    • Basic Authorization;
    • API Key;
    • Sin autenticación.
  • Para OAuth2, se debe proporcionar la siguiente información:
    • endpoint del webhook;
    • URL del proveedor OAuth2;
    • ClientId del proveedor OAuth2;
    • Secret del proveedor OAuth2.
  • Para Basic Authorization, es necesario enviarlo en el formato user:pass.
  • Para API Key, son posibles dos formatos:
    • header:value, cuando se desea un nombre de header específico;
    • value, cuando el header deseado es Authorization.
  • Configuración de reintentos: Indica el número de intentos en caso de fallo al llamar al endpoint:
    • Número máximo de intentos;
    • Intervalo entre intentos (en segundos);
    • Rate Limit: Número máximo de envíos simultáneos (máximo: 500);
    • Timeout: Tiempo máximo de espera para la respuesta del endpoint (en segundos).
  • Estados a notificar: Puedes suscribirte a estados específicos para recibir notificaciones. Estos incluyen:
    • approved: Transacción aprobada;
    • processing: Transacción en procesamiento;
    • inconclusive: No pudimos realizar una validación concluyente;
    • shared: Transacción compartida, esperando el envío;
    • skipped: La persona omitió la captura biométrica en el flujo;
    • unknown-share: La persona indicó que no reconoce la compra;
    • absent-holder: El titular de la tarjeta no está presente para realizar la captura;
    • expired: La persona no completó la captura dentro del tiempo establecido y la transacción expiró.
Sobre la autenticación

La API puede protegerse mediante un método de autenticación como Basic Authentication o API Key. También se puede definir una lista de IPs válidas para el acceso, como protección adicional.

Integración con Verificación de Tarjeta No Presente​

Al configurar un webhook en la plataforma, puedes recibir información sobre los procesos a través de notificaciones enviadas a un endpoint de la API que desarrollaste para recibir estas actualizaciones.

La información enviada por la plataforma a la API incluye:

  • ID: ID de la transacción;
  • Status: Estado de la transacción;
  • HasIdentityChanged: Si ocurrió un cambio de identidad en la transacción (opcional).
nota

Ten en cuenta que es posible elegir los estados sobre los que el cliente desea ser notificado mediante la configuración del webhook. Después de enviar esta información, se espera que la respuesta sea síncrona.

Solicitudes​

La solicitud debe ser un método POST a una API REST, lo que facilita y da mayor seguridad al envío de la información. Todos los campos deben ser obligatorios. El cuerpo de la solicitud debe aceptar el ID y el estado de la transacción, como se muestra en el siguiente ejemplo:

{
  "id": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "status": "approved",
  "hasIdentityChanged": false
}

Respuesta​

La respuesta debe ser síncrona. El estado para las solicitudes exitosas debe estar en el rango de 200 a 299. Cualquier otro estado se considerará un fallo, y Verificación de Tarjeta No Presente realizará intentos adicionales de notificación (con exponential backoff entre ellos), hasta recibir una respuesta 2xx o alcanzar el número máximo de intentos.

Estado de la respuesta​

Actualmente contamos con un conjunto de estados, pero este conjunto puede cambiar en el futuro. Por lo tanto, se recomienda hacer configurables los estados que le interesan al cliente para tomar acción. Por ejemplo, si la intención es actuar cada vez que una captura se completa con éxito, actualmente esto ocurre con el estado "processing". Sin embargo, dado que esto podría modificarse en el futuro, se recomienda que el estado que indica una captura exitosa sea configurable en el sistema, de modo que un futuro cambio al estado "captured" pueda implementarse fácilmente.

Además, recomendamos tener acciones específicas para estados específicos y una acción general en caso de que el estado no sea reconocido (por ejemplo, asumiendo que cualquier valor diferente de "processing" y "approved" es inconcluso). Esto es importante porque en el futuro pueden aparecer nuevos estados, y no se espera que el webhook falle debido a esto.

Consideraciones importantes​

Presta atención a los siguientes aspectos al desarrollar la API que Verificación de Tarjeta No Presente utilizará para notificar los cambios de estado:

Rate limit — Para evitar sobrecargar tus recursos en situaciones con muchas transacciones, es posible especificar un límite superior en la cantidad de veces que se puede invocar el endpoint.

Error Rate — La tasa de error (respuestas fuera del rango [200, 299]) debe mantenerse siempre baja. De lo contrario, el throughput del webhook se reducirá automáticamente, y esta reducción, combinada con el mecanismo de reintentos, puede resultar en un mayor tiempo de ejecución para los nuevos webhooks.

Idempotencia — La implementación actual del webhook garantiza la entrega al menos una vez (at-least-once), por lo que el mismo estado puede notificarse más de una vez. Por lo tanto, la implementación del endpoint debe realizarse de manera idempotente.

Fallback — En caso de alguna indisponibilidad en el servicio de webhook, se recomienda contar con un método de fallback para poder seguir obteniendo los estados de las transacciones dentro del tiempo de respuesta establecido. La consulta al endpoint se describe en la sección Referencia de la API de esta documentación.

Última actualización el