Webhooks
Dónde se entregan los resultados, qué eventos van a cada sitio y los avisos que te dicen que nadie está escuchando
Un endpoint de webhook es una URL tuya a la que enviamos eventos a medida que ocurren las verificaciones. Es la forma en que tus propios sistemas conocen el resultado sin tener que consultarnos.
Registrar un endpoint es tarea de quien gestiona tus servidores. Leer esta página para averiguar por qué algo no llegó es tarea de cualquiera.
Registrar un endpoint
Indícanos una URL HTTPS que controles. Te enviaremos cargas de eventos firmadas. El entorno se fija al registrar el endpoint y no puede cambiarse después, así que un endpoint de sandbox seguirá siendo de sandbox para siempre.
La descripción opcional es tu propia etiqueta. Vale la pena rellenarla, porque el enrutamiento por clave hace que dos endpoints en el mismo host sean algo totalmente normal, y el nombre es lo que los distingue en la lista.
El secreto de firma se muestra una vez al crear el endpoint, y otra vez si lo rotas. Rotarlo lo sustituye de inmediato, sin solapamiento, así que las entregas fallarán la verificación de firma de tu lado hasta que despliegues el secreto nuevo. Ambas acciones piden un código de tu app de autenticación.
Elegir eventos
Un endpoint solo recibe los eventos a los que está suscrito. Los más habituales:
| Evento | Cuándo se envía |
|---|---|
verification.created | Se creó una sesión |
verification.approved | El veredicto es aprobar |
verification.rejected | El veredicto es rechazar |
verification.review | El veredicto es revisar, y una persona tiene que mirarlo |
verification.expired | El solicitante no completó la sesión a tiempo |
verification.corrected | Un resultado que ya te enviamos era incorrecto y se ha corregido |
verification.data_updated | Alguien de tu equipo editó los datos del solicitante. El resultado no cambia; vuelve a obtener la verificación para ver los valores nuevos |
verification.completed | La sesión llegó a un estado final, para cualquier resultado |
Un endpoint nuevo empieza con aprobado, rechazado, revisión, expirado y verification.data_updated
ya marcados, y puedes cambiar la selección antes de guardar. A todos los endpoints que existían antes
de que se pudieran editar los datos de los solicitantes y que estaban suscritos al menos a un evento
se les añadió verification.data_updated automáticamente.
El catálogo completo, con las cargas, está en Eventos de webhook.
No te suscribas a completed y a los eventos de cada veredicto a la vez
verification.completed se envía junto con los eventos de veredicto, así que elegir ambos entrega
cada resultado dos veces. El selector te avisa cuando estás a punto de hacerlo.
Un endpoint que no está suscrito a nada no recibe nada, y la lista lo indica claramente. Lo mismo ocurre con un endpoint suscrito a un nombre de evento que ya nada envía.
Enrutamiento por clave de API
Cada evento se asocia a la clave de API que creó la sesión, y así es como una cuenta que gestiona varios negocios envía los resultados de cada uno a su propio sistema.
Un endpoint está configurado para Todas las claves API, lo que significa todas las verificaciones de ese entorno, incluidas las sesiones creadas sin clave, o limitado a claves concretas.
La consola vigila las dos formas en que esto sale mal y te lo dice antes de que lo hagan tus clientes.
Una clave que nadie recibe. Crear una clave de API no la suscribe a nada, así que las verificaciones hechas con ella no van a ninguna parte hasta que la añadas a un endpoint o configures un endpoint para todas las claves.
Nadie recibe las sesiones sin clave. Una verificación iniciada desde esta consola no lleva clave de API, así que solo llega a un endpoint configurado para todas las claves. Si todos los endpoints están limitados a claves concretas, esas sesiones no se entregan a ninguna parte.
Probar antes de confiar
Enviar evento de prueba envía ahora mismo una carga de ejemplo al endpoint, firmada con su secreto actual. No trata de nadie: los identificadores que contiene son claramente falsos y el sobre está marcado como prueba, para que tu manejador pueda distinguirlo del tráfico real. Por lo demás, el cuerpo coincide con lo que enviamos de verdad, así que un manejador que acepta la prueba acepta lo real.
Hay un breve tiempo de espera entre pruebas.
Seguir las entregas
Cada endpoint tiene un panel con el tráfico reciente: todo aceptado, nada pendiente, nada reintentado, o los fallos si los hay. Indica claramente cuando todavía no se ha enviado nada.
El historial de entregas procede de los registros de integración, así que un rol sin Registros ve el endpoint pero no sus cargas. Ese límite existe porque una carga almacenada es una copia literal de lo que enviamos sobre un solicitante.
Para el historial completo, los filtros y la posibilidad de reenviar una entrega concreta, ve a Registros.
Deshabilitar y eliminar
Deshabilitar detiene las entregas hasta que vuelvas a habilitarlo, que es lo que conviene durante un mantenimiento de tu lado. Eliminar es permanente, y dejamos de enviar a esa URL por completo.
Ninguna de las dos acciones pierde las verificaciones. Los eventos que no se pudieron entregar se reintentan, y una entrega puede reenviarse a mano más adelante.
Recibir un aviso cuando algo falla
Añade direcciones de alertas para desarrolladores en Configuración y les enviaremos un correo cuando tu integración pierda un evento. Las alertas sobre un mismo endpoint se agrupan, así que una caída es un solo mensaje y no uno por cada evento perdido. Sin ellas, nadie recibe aviso.