Eventos

Estructura común

Todos los eventos siguen este shape base:

{
  "object": "event",
  "id": "evt_4f7c9a2b8d1e3506",
  "type": "link.refreshed",
  "created_at": "2026-06-03T15:00:45Z",
  "data": { /* shape varía por type */ }
}

Campo	Tipo	Significa
`id`	string	`evt_` + 16 hex. Único por evento. Úsalo como dedup key.
`type`	string	Tipo del evento (ver catálogo abajo)
`created_at`	ISO 8601	Cuándo se emitió el evento
`data`	object	El recurso afectado en su estado actual (post-update)

Catálogo de eventos

`link.created`

Dispara después de un exchange exitoso. Acaba de nacer el link.

{
  "object": "event",
  "id": "evt_xxx",
  "type": "link.created",
  "created_at": "2026-06-03T15:00:45Z",
  "data": {
    "object": "link",
    "id": "link_8a2f4c6e1b9d5037",
    "bank_id": "banco_estado",
    "status": "active",
    "holder_name": "JANE DOE EXAMPLE",
    "created_at": "2026-06-03T15:00:45Z"
  }
}

`link.refreshed`

El sync (automático cada 4h o on-demand) terminó OK. Trae los accounts_count actualizados.

{
  "object": "event",
  "id": "evt_xxx",
  "type": "link.refreshed",
  "created_at": "2026-06-03T15:00:45Z",
  "data": {
    "object": "link",
    "id": "link_8a2f4c6e1b9d5037",
    "status": "active",
    "last_synced_at": "2026-06-03T15:00:45Z",
    "next_sync_at": "2026-06-03T19:00:45Z",
    "accounts_count": 3,
    "new_movements_count": 5
  }
}

`link.expired`

3 fallos consecutivos sin validar. El user debe re-conectar (widget nuevo).

{
  "object": "event",
  "id": "evt_xxx",
  "type": "link.expired",
  "created_at": "2026-06-03T15:00:45Z",
  "data": {
    "object": "link",
    "id": "link_8a2f4c6e1b9d5037",
    "status": "expired",
    "last_error_code": "rejected_credentials",
    "expired_at": "2026-06-03T15:00:45Z"
  }
}

`link.deleted`

El cliente borró el link via DELETE /v1/links/{id}. Las cuentas y movs asociados también se borraron.

{
  "object": "event",
  "id": "evt_xxx",
  "type": "link.deleted",
  "created_at": "2026-06-03T15:00:45Z",
  "data": {
    "object": "link",
    "id": "link_8a2f4c6e1b9d5037",
    "deleted_at": "2026-06-03T15:00:45Z"
  }
}

`account.created`

Apareció una cuenta nueva en el banco bajo un link existente. Útil cuando el user abre una cuenta vista nueva, por ejemplo.

{
  "object": "event",
  "id": "evt_xxx",
  "type": "account.created",
  "created_at": "2026-06-03T15:00:45Z",
  "data": {
    "object": "account",
    "id": "acc_5b1e4f7a3c9d6280",
    "link_id": "link_8a2f4c6e1b9d5037",
    "name": "Cuenta Vista",
    "type": "checking",
    "currency": "CLP",
    "last_4": "9876"
  }
}

`account.removed`

Una cuenta dejó de aparecer en el banco (cerrada o transferida). Queda marcada como status: removed en Rail pero no se borra — para auditoría puedes seguir viendo sus movs históricos con ?include_removed=true.

{
  "object": "event",
  "id": "evt_xxx",
  "type": "account.removed",
  "created_at": "2026-06-03T15:00:45Z",
  "data": {
    "object": "account",
    "id": "acc_5b1e4f7a3c9d6280",
    "link_id": "link_8a2f4c6e1b9d5037",
    "status": "removed",
    "removed_at": "2026-06-03T15:00:45Z"
  }
}

`refresh_intent.created`

Un refresh_intent fue encolado.

{
  "object": "event",
  "id": "evt_xxx",
  "type": "refresh_intent.created",
  "created_at": "2026-06-03T15:00:00Z",
  "data": {
    "object": "refresh_intent",
    "id": "ri_a1b2c3d4e5f6a7b8",
    "link_id": "link_8a2f4c6e1b9d5037",
    "status": "created",
    "refresh_type": "full"
  }
}

`refresh_intent.requires_mfa`

El banco pidió MFA. Tu app debe abrir el widget con data.requires_mfa.widget_token. Ver Manejo de MFA.

{
  "object": "event",
  "id": "evt_xxx",
  "type": "refresh_intent.requires_mfa",
  "created_at": "2026-06-03T15:00:15Z",
  "data": {
    "object": "refresh_intent",
    "id": "ri_a1b2c3d4e5f6a7b8",
    "link_id": "link_8a2f4c6e1b9d5037",
    "status": "requires_mfa",
    "requires_mfa": {
      "widget_token": "ri_a1b2c3d4e5f6a7b8_sec_…",
      "expires_at": "2026-06-03T15:10:15Z"
    }
  }
}

`refresh_intent.succeeded`

Sync on-demand terminó OK.

{
  "object": "event",
  "id": "evt_xxx",
  "type": "refresh_intent.succeeded",
  "created_at": "2026-06-03T15:00:45Z",
  "data": {
    "object": "refresh_intent",
    "id": "ri_a1b2c3d4e5f6a7b8",
    "link_id": "link_8a2f4c6e1b9d5037",
    "status": "succeeded",
    "completed_at": "2026-06-03T15:00:45Z",
    "summary": {
      "accounts_updated": 3,
      "new_movements_count": 5
    }
  }
}

`refresh_intent.failed`

Sync on-demand falló. Ver error_code en Errores → Bancos.

{
  "object": "event",
  "id": "evt_xxx",
  "type": "refresh_intent.failed",
  "created_at": "2026-06-03T15:00:45Z",
  "data": {
    "object": "refresh_intent",
    "id": "ri_a1b2c3d4e5f6a7b8",
    "link_id": "link_8a2f4c6e1b9d5037",
    "status": "failed",
    "error_code": "bank_unavailable",
    "completed_at": "2026-06-03T15:00:45Z"
  }
}

Suscribirse a tipos específicos

Cuando creas un webhook endpoint, especificas qué eventos quieres:

curl https://api.rail.cl/v1/webhook_endpoints \
  -X POST \
  -H "Authorization: Bearer rail_sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-app.com/webhooks/rail",
    "enabled_events": [
      "link.refreshed",
      "link.expired",
      "refresh_intent.succeeded",
      "refresh_intent.failed",
      "refresh_intent.requires_mfa"
    ]
  }'

Para recibir todos los eventos, usa ["*"]. No recomendado en producción — quedas expuesto a eventos nuevos que tu handler no espera.

Probar webhooks

Desde el dashboard (Webhooks → Endpoint → “Send test event”) puedes disparar un evento dummy de cualquier tipo. Útil para validar tu firma + handler antes de tener data real.

Empezar

Conceptos

Guías

Estructura común

Catálogo de eventos

`link.created`

`link.refreshed`

`link.expired`

`link.deleted`

`account.created`

`account.removed`

`refresh_intent.created`

`refresh_intent.requires_mfa`

`refresh_intent.succeeded`

`refresh_intent.failed`

Suscribirse a tipos específicos

Probar webhooks

​Estructura común

​Catálogo de eventos

​link.created

​link.refreshed

​link.expired

​link.deleted

​account.created

​account.removed

​refresh_intent.created

​refresh_intent.requires_mfa

​refresh_intent.succeeded

​refresh_intent.failed

​Suscribirse a tipos específicos

​Probar webhooks

Estructura común

Catálogo de eventos

`link.created`

`link.refreshed`

`link.expired`

`link.deleted`

`account.created`

`account.removed`

`refresh_intent.created`

`refresh_intent.requires_mfa`

`refresh_intent.succeeded`

`refresh_intent.failed`

Suscribirse a tipos específicos

Probar webhooks