Catálogo de eventos
Catálogo de eventos
Soyio emite eventos en dos capas. Este catálogo las reúne en un solo lugar, con el nombre de cada evento, cuándo se emite y el enlace a su contrato.
| Capa | Dónde llega | Para qué sirve |
|---|---|---|
| Webhooks | Tu servidor, vía HTTP POST | Sincronizar tu base de datos y disparar procesos de backend |
| SDK y embeds | El navegador del usuario, vía onEvent | Reaccionar en la UI y hacer tracking de analítica en tiempo real |
Las dos capas son complementarias, pero no equivalentes: cada módulo emite los eventos de sus propios flujos y con su propia nomenclatura (snake_case con punto en los webhooks, SCREAMING_SNAKE_CASE en el SDK), así que no asumas un par uno a uno entre un evento de frontend y un webhook. Usa los eventos de SDK para la UI y la analítica, y los webhooks como fuente de verdad de lo que quedó registrado en Soyio.
Eventos de webhooks
Cuando algo relevante ocurre en tu cuenta, Soyio crea un objeto de evento y lo envía a los webhooks suscritos:
{
"id": "evt_1B2M2Y8AsgTpgAmY7PhCfg",
"name": "disclosure_request.granted",
"payload": {
"disclosure_request_id": "dreq_1B2M2Y8AsgTpgAmY7PhCfg",
"identity_id": "id_ma21KLsmaslopask912Aa2",
"user_reference": "user_123"
},
"created_at": "2024-03-20T15:30:00Z"
}
Para entrega, reintentos, alertas y verificación de firma revisa la guía de webhooks. Si necesitas los contratos en formato máquina, consulta el endpoint de contratos de eventos.
Hoy existen 34 eventos agrupados en 15 dominios. Cada dominio tiene su propio wildcard de suscripción.
agreement.*
| Evento | Cuándo se emite | Contrato |
|---|---|---|
agreement.created | Se crea un nuevo agreement | Ver contrato |
agreement.updated | Se actualiza un agreement existente | Ver contrato |
agreement.data_permissions_expired | Uno o más data_permissions del agreement expiran, así que el tratamiento asociado debe cesar | Ver contrato |
api_key.*
| Evento | Cuándo se emite | Contrato |
|---|---|---|
api_key.created | Se crea una nueva API key | Ver contrato |
api_key.updated | Se actualiza una API key existente | Ver contrato |
api_key.destroyed | Se elimina una API key | Ver contrato |
auth_attempt.*
| Evento | Cuándo se emite | Contrato |
|---|---|---|
auth_attempt.successful | Un intento de autenticación se completa con éxito | Ver contrato |
auth_attempt.failed | Un intento de autenticación falla | Ver contrato |
auth_request.*
| Evento | Cuándo se emite | Contrato |
|---|---|---|
auth_request.successful | Un auth request se completa con éxito | Ver contrato |
consent_action.*
| Evento | Cuándo se emite | Contrato |
|---|---|---|
consent_action.created | Se crea una nueva acción de consentimiento (grant o revoke) | Ver contrato |
consent_action.redec_receipt_generated | Se genera el PDF de recibo REDEC de una acción de consentimiento | Ver contrato |
consent_action.redec_receipt_generated aparece bajo la etiqueta REDEC en la especificación, pero se suscribe con consent_action.*.
consent_commit.*
| Evento | Cuándo se emite | Contrato |
|---|---|---|
consent_commit.created | Se crea una nueva agrupación de acciones de consentimiento | Ver contrato |
consent_form_entry.*
| Evento | Cuándo se emite | Contrato |
|---|---|---|
consent_form_entry.created | Se persiste el envío de un formulario de consentimiento | Ver contrato |
consent_form_entry.updated | Se actualiza el registro, hoy solo su user_reference | Ver contrato |
consent_form_entry.destroyed | Se revierte o elimina el registro, lo que invalida un created previo | Ver contrato |
consent_form_entry.created no es fuente de verdad del consentimiento otorgado: llega con consent_action_id: null y granted_template_ids: []. Revisa el detalle en Orden de emisión y fuente de verdad.
data_subject_request.*
| Evento | Cuándo se emite | Contrato |
|---|---|---|
data_subject_request.created | Se crea una nueva solicitud de ejercicio de derechos | Ver contrato |
data_subject_request.updated | Se actualiza una solicitud existente | Ver contrato |
data_subject_request.validating | La solicitud entra en proceso de validación de identidad | Ver contrato |
data_subject_request.processing | La validación resulta exitosa y la solicitud entra en procesamiento | Ver contrato |
data_subject_request.data_missmatch | La validación se completa, pero los datos no coinciden con los de la solicitud | Ver contrato |
data_subject_request.resolved | La solicitud se resuelve, sea aprobada o rechazada | Ver contrato |
disclosure_request.*
| Evento | Cuándo se emite | Contrato |
|---|---|---|
disclosure_request.granted | El disclosure request se completa y se otorga acceso a los datos | Ver contrato |
disclosure_request.failed | El disclosure request falla durante el proceso | Ver contrato |
disclosure_request.timed_out | El disclosure request expira sin completarse | Ver contrato |
export.*
| Evento | Cuándo se emite | Contrato |
|---|---|---|
export.completed | Una exportación asíncrona termina y el archivo queda disponible | Ver contrato |
export.failed | Una exportación asíncrona falla, con el motivo en error_message | Ver contrato |
government_check_request.*
| Evento | Cuándo se emite | Contrato |
|---|---|---|
government_check_request.successful | Un government check request se completa con éxito | Ver contrato |
government_check_request.failed | Un government check request falla | Ver contrato |
redec.*
| Evento | Cuándo se emite | Contrato |
|---|---|---|
redec.rdc40_no_changes | No hubo eventos que gatillen el reporte RDC40 en las últimas 24 horas | Ver contrato |
report.*
| Evento | Cuándo se emite | Contrato |
|---|---|---|
report.created | Se genera un nuevo reporte | Ver contrato |
redec.rdc40_no_changes y report.created comparten la etiqueta Reports en la especificación, pero se suscriben por separado con redec.* y report.*.
signature_attempt.*
| Evento | Cuándo se emite | Contrato |
|---|---|---|
signature_attempt.successful | Un intento de firma se completa con éxito | Ver contrato |
signature_attempt.failed | Un intento de firma falla | Ver contrato |
validation_attempt.*
| Evento | Cuándo se emite | Contrato |
|---|---|---|
validation_attempt.successful | Un intento de validación de identidad se completa con éxito | Ver contrato |
validation_attempt.failed | Un intento de validación de identidad falla | Ver contrato |
Wildcards de suscripción
Al crear un webhook puedes elegir eventos individuales, un dominio completo o todo. Estos son los valores válidos de wildcard:
*, agreement.*, api_key.*, auth_attempt.*, auth_request.*, consent_action.*, consent_commit.*, consent_form_entry.*, data_subject_request.*, disclosure_request.*, export.*, government_check_request.*, redec.*, report.*, signature_attempt.*, validation_attempt.*
No recomendamos el wildcard * en producción. Nuestros eventos son altamente transaccionales, así que suscribirte a todo genera un volumen de entregas que tu servidor debe procesar y descartar sin necesidad. Úsalo solo para explorar en sandbox.
Suscríbete solo a lo que tu aplicación procesa. Revisa el detalle en Suscripción a eventos.
Eventos de SDK y embeds
Todos los eventos del SDK web llegan por el callback onEvent y traen un campo eventName que actúa como discriminador. Si usas TypeScript, importa los tipos desde @soyio/soyio-widget para obtener autocompletado y type narrowing.
Widget popup
Aplican a los flujos de disclosure, firma y autenticación que abren el popup de Soyio. Tipo: EventData.
| Evento | Cuándo se emite | Payload (además de eventName) | Guía |
|---|---|---|---|
DISCLOSURE_REQUEST_SUCCESSFUL | El usuario completa el flujo de disclosure | userReference, identityId | Valida la identidad |
AUTH_REQUEST_SUCCESSFUL | Nombre declarado para el término del auth request | userReference, identityId | Autentica usuarios |
IDENTITY_SIGNATURE | El usuario completa el proceso de firma | userReference, identityId | Firma documentos |
REJECTED_SIGNATURE | El usuario cancela el proceso de firma | — | Firma documentos |
DENIED_CAMERA_PERMISSION | El usuario rechaza el permiso de cámara | — | Valida la identidad |
UNEXPECTED_ERROR | Ocurre un error inesperado en el flujo | — | Maneja errores |
WIDGET_OPENED | El popup de Soyio se abre | — | Valida la identidad |
WIDGET_CLOSED | El usuario cierra el popup de Soyio | — | Valida la identidad |
CLOSE_POPUP | El popup entrega hoy este nombre al terminar el auth request | userReference, identityId | Autentica usuarios |
Al término de un auth request, el popup entrega hoy CLOSE_POPUP y no AUTH_REQUEST_SUCCESSFUL. Maneja ambos nombres mientras se alinean SDK y aplicación, y confirma el resultado con el webhook auth_request.successful.
EventData declara además IDENTITY_VALIDATED e IDENTITY_AUTHENTICATED. Se mantienen por compatibilidad de tipos y ningún flujo los emite: escucha DISCLOSURE_REQUEST_SUCCESSFUL para disclosure e IDENTITY_SIGNATURE para firma.
Passkeys en DisclosureRequestBox
Solo aplican al embed DisclosureRequestBox, que delega el registro y la autenticación con llave de acceso a tu aplicación.
| Evento | Cuándo se emite | Payload (además de eventName) | Guía |
|---|---|---|---|
PASSKEY_REQUIRED | El flujo necesita registrar una llave de acceso | type, sessionToken, companyId | Disclosure embebido |
PASSKEY_AUTHENTICATION_REQUIRED | El flujo necesita autenticar con una llave de acceso existente | type, requestableToken | Disclosure embebido |
PASSKEY_REGISTERED | La llave de acceso queda registrada | type, identifier | Disclosure embebido |
PASSKEY_AUTHENTICATED | La autenticación con llave de acceso resulta exitosa | type, identifier | Disclosure embebido |
Privacy Center
Tipo: PrivacyCenterEvent.
| Evento | Cuándo se emite | Payload (además de eventName) | Guía |
|---|---|---|---|
REQUEST_SUBMITTED | El usuario envía una solicitud de ejercicio de derechos | dataSubjectRequestId, kind, entityId | Eventos del Privacy Center |
REQUEST_SUBMISSION_FAILED | El envío de la solicitud falla | kind, errorCode?, errorMessage? | Eventos del Privacy Center |
VALIDATION_SUCCESSFUL | La validación de identidad asociada termina con éxito | dataSubjectRequestId | Eventos del Privacy Center |
VALIDATION_FAILED | La validación de identidad falla | dataSubjectRequestId, errorReason? | Eventos del Privacy Center |
CONSENT_UPDATED | El usuario otorga o revoca un consentimiento en modo immediate | consentTemplateId, action, actionToken? | Gestiona consentimientos |
CONSENT_UPDATE_FAILED | Una operación de consentimiento falla en modo immediate | consentTemplateId, action, errorCode? | Gestiona consentimientos |
CONSENT_BATCH_UPDATED | El usuario guarda un conjunto de consentimientos en modo batch | updates | Gestiona consentimientos |
CONSENT_BATCH_UPDATE_FAILED | El guardado del conjunto falla en modo batch | consentTemplateIds, errorCode? | Gestiona consentimientos |
UNEXPECTED_ERROR | Error no clasificado dentro del flujo | context, errorMessage? | Eventos del Privacy Center |
Checkbox de consentimiento
Tipo: ConsentEvent.
| Evento | Cuándo se emite | Payload (además de eventName) | Guía |
|---|---|---|---|
CONSENT_CHECKBOX_CHANGE | El usuario marca o desmarca el checkbox de consentimiento | isSelected, actionToken?, identifier | Captura consentimiento |
Formulario de consentimiento
Tipo: ConsentFormEvent.
| Evento | Cuándo se emite | Payload (además de eventName) | Guía |
|---|---|---|---|
CONSENT_FORM_SUBMITTED | El registro del envío se persiste | entryToken, redirectUrl | Embebe el formulario |
CONSENT_FORM_COMPLETED | El usuario hace clic en el botón final de la pantalla de éxito | entryToken, redirectUrl | Embebe el formulario |
CONSENT_FORM_PAGE_CHANGE | El usuario avanza o retrocede de página | currentPage, totalPages | Embebe el formulario |
CONSENT_FORM_LOAD_ERROR | El formulario no carga, por ejemplo si el host no está permitido | kind, message? | Embebe el formulario |
CONSENT_FORM_SUBMIT_ERROR | El envío del formulario falla | message | Embebe el formulario |
SDK móvil
El SDK de React Native usa el campo type en vez de eventName y tiene nombres propios, como SUCCESS para el término exitoso del flujo o WEBVIEW_PROCESS_TERMINATED cuando el sistema operativo mata el webview. No asumas paridad de nombres con el SDK web.