Primeros pasos
En Auco, para darte control total de la integración con cada uno de los procesos creados, contamos con un sistema webhook en el que podrás recibir notificaciones en cada etapa de cada uno de los flujos creados, de inicio a fin.
Para configurar el webhook existen dos caminos, desde el API y la plataforma web:
Creación desde app.auco.ai:
Es importante que para realizar esta configuración seas admin o tengas permisos admin, desde la plataforma solo podrás crear un webhook, que será el webhook 'default'.
- Ingresa con tu correo y contraseña.
- Dirígete al perfil www.auco.ai/profile
- ingresa a opciones de desarrollo
- En la parte inferior encontrarás las opciones para modificar tu webhook y headers de autenticación si requieres.
Creación desde Auco API
🆕 Si! Desde el API es posible crear diferentes webhook, cada webhook debe tener un id, tu primer webhook debe tener el id 'default', que es donde por defecto se van a enviar todas las notificaciones; los siguientes webhooks pueden tener el id que prefieras.
Para definir a qué webhooks se notificarán los estados del proceso, en la creación del documento, debes guardar la lista de ids de los webhooks a los que se debe notificar.
Autenticación
Incluye tu llave privada en el encabezado Authorization.
Authorization: prk_xxx...
Parámetros de creación de webhooks
| Nombre | Tipo | Descripción |
|---|---|---|
id | String requerido | Nombre identificador del webhook, el primer webhook debe ser default. |
description | String opcional | Descripción del propósito del webhook. |
url | String requerido | URL (URI válida) a la que se enviarán las notificaciones del webhook. |
header | Object opcional | Objeto { key, value } con el header de autenticación a enviar. |
header.key | String condicional | Subcampo de header. Requerido si se envía header: clave del header. |
header.value | String condicional | Subcampo de header. Requerido si se envía header: valor del header. |
¿Dónde se configuran?
Los webhooks se guardan mediante el endpoint Actualizar organización (PUT /v1.5/ext/company), en el parámetro webhooks. Allí encontrarás los ejemplos completos de la petición en Curl, Python y Node.js.
👉 Ver Actualizar organización.
El parámetro webhooks reemplaza la configuración existente: debes enviar la lista completa e incluir siempre el webhook con id: "default". Para conservar webhooks ya creados, inclúyelos en la petición.
Señales del guardián de identidad
Cuando la validación de identidad de un firmante o de un proceso AucoFace pasa por el guardián de identidad de Auco, la notificación incluye el campo signals: la lista de señales antifraude que el guardián registró en esa validación.
"signals": [
{ "code": "ALERT_FACE", "severity": "ALERT" },
{ "code": "ALERT_EMAIL_CHANGED", "severity": "INFO" }
]
severity | Significado | Detuvo el proceso |
|---|---|---|
REPORT | Coincidencia con una lista de bloqueo. | Sí |
ALERT | Alerta de fraude según la configuración de tu organización. | Sí |
INFO | Señal informativa: quedó registrada, pero no bloqueó el proceso. | No |
severity, no por el codeLa severidad de los códigos ALERT_* depende de la configuración de cada organización: el mismo código puede llegar como INFO o como ALERT. Usa severity para saber si la señal bloqueó.
signals llega en las notificaciones de firma (NOTIFICATION) y de bloqueo (BLOCKED) de documentos y paquetes, y en todas las notificaciones de AucoFace. No viene cuando la validación no llegó al guardián —por ejemplo, porque falló antes la comparación facial— ni cuando la lista está vacía. Trata un code que no reconozcas como una señal más: pueden aparecer códigos nuevos.
code | Significado |
|---|---|
REPORT | La persona está en una lista de bloqueo. |
REPORT_EMAIL | El correo está en una lista de bloqueo. |
REPORT_PHONE | El teléfono está en una lista de bloqueo. |
REPORT_FACE | El rostro está en una lista de bloqueo. |
REPORT_DECEASED | El documento pertenece a una persona fallecida. |
REPORT_FACE_MISMATCH | El rostro no coincide con el de su enrolamiento. |
ALERT_FACE | El rostro pertenece a otra persona registrada. |
ALERT_IDENTITY_MISMATCH | Los datos no coinciden con el registro civil. |
ALERT_IDENTIFICATION_NOT_FOUND | El documento no existe en el registro civil. |
ALERT_EMAIL_CHANGED | La persona usa un correo distinto al registrado. |
ALERT_PHONE_CHANGED | La persona usa un teléfono distinto al registrado. |
ALERT_EMAIL | El correo ya está asociado a otra persona. |
ALERT_PHONE | El teléfono ya está asociado a otra persona. |
ALERT_DEVICE | El dispositivo fue usado por varias personas. |
ALERT_IP | La IP fue usada por varias personas. |
ALERT_LOCATION | La ubicación es inusual para esta persona. |
Tiempo de respuesta y reintentos
Auco espera máximo 10 segundos la respuesta de tu endpoint. Si tu servidor no responde dentro de esa ventana, Auco corta la conexión y la notificación queda registrada como timeout.
Esos 10 segundos cubren la petición completa: resolución DNS, handshake TLS y el tiempo que tarde tu servidor en responder. Un endpoint que en promedio tarda 8 segundos ya está al límite.
Devuelve 200 apenas recibas la notificación y encola el trabajo pesado —guardar en base de datos, descargar el PDF, llamar a otro servicio— en segundo plano.
Un handler que descarga archivos o consulta a un tercero de forma síncrona antes de responder supera los 10 segundos con facilidad, y la notificación se corta aunque tu código haya terminado bien.
Reintentos
Una notificación cuenta como entregada solo si tu endpoint responde con un código 2xx. Si falla —por timeout, o porque respondes 4xx o 5xx— Auco la reintenta hasta 3 veces, esperando cada vez un poco más:
| Reintento | Cuándo |
|---|---|
| 1.º | 2 minutos después del intento fallido |
| 2.º | 4 minutos después del anterior |
| 3.º | 6 minutos después del anterior |
Después del tercer reintento Auco deja de intentar y esa notificación se descarta: no vuelve a enviarse.
4xx no cancela la notificaciónResponder con un código de error no le dice a Auco que descarte el evento: dispara la misma cadena de reintentos que un timeout. Si tu integración decide ignorar un status, respóndele 200 igual y descártalo de tu lado.
Un reintento repite la misma notificación. Si tu servidor alcanzó a procesarla pero respondió tarde, vas a recibirla otra vez. Usa el code del proceso junto con el status para reconocer una repetición, en lugar de crear un registro nuevo en cada llegada.
Como una notificación descartada no se reenvía, no dependas solo del webhook para saber en qué va un proceso. Puedes consultar su estado cuando lo necesites con Consultar proceso.
⚠️ Respuestas de error
| Código | Descripción |
|---|---|
| 400 | Falta el webhook default |
| 401 | Autenticación inválida o ausente |