# Eventos (/docs/events)

<Endpoint method="GET" path="/v1/events" href="/docs/api/events/list-events" />

Cada cambio importante genera un evento. Llega por [webhook](/docs/webhooks) y queda en `GET /v1/events`, con la misma forma:

```json
{
  "id": "evt_01m3sgb02af7nb0jf73vwv2sd5",
  "type": "payin.completed",
  "schema_version": 1,
  "occurred_at": "2026-10-18T12:03:12.418Z",
  "livemode": false,
  "data": {
    "id": "pin_01m3sg9x0000000000000000",
    "status": "completed",
    "funding_account_id": "fa_01m3sg9w0000000000000000",
    "amount": "45.871200",
    "currency": "USDT",
    "created_at": "2026-10-18T12:03:10Z",
    "completed_at": "2026-10-18T12:03:12Z"
  }
}
```

| Campo | Qué es |
| --- | --- |
| `id` | El id del evento. Úsalo para no procesar dos veces el mismo. |
| `type` | Qué pasó. |
| `schema_version` | La versión de la forma de `data` para ese tipo. Hoy, `1`. |
| `occurred_at` | Cuándo pasó. |
| `livemode` | `true` en live, `false` en sandbox. |
| `data` | El recurso, con la forma de la API. Puede ganar campos nuevos. |

Los eventos nunca traen datos de cuentas de beneficiarios ni datos personales de tus clientes.

## Leer el registro [#leer-el-registro]

```bash
curl "$CAIBO_API/v1/events?after=$CURSOR&limit=100" -H "Authorization: Bearer $CAIBO_API_KEY"
```

- Del **más antiguo al más nuevo**. Guarda `next_cursor` (viene siempre) y continúa desde ahí: nunca te saltas un evento.
- `type` filtra por un tipo exacto (`payout.completed`) o por una familia terminada en punto (`payout.`).
- `resource_id` trae la historia de un recurso: `?resource_id=pout_…`.
- Un evento recién ocurrido puede tardar un instante en aparecer en la lista; el webhook no espera.

## Catálogo [#catálogo]

<Accordions>
<Accordion title="Cobros">
`funding_account.active`, `funding_account.failed`, `payin.completed`, `payin.failed`
</Accordion>
<Accordion title="Pagos">
`payout.created`, `payout.completed`, `payout.failed`, `payout.cancelled`, `payout.returned`, `payout.return_settled`
</Accordion>
<Accordion title="Pagos en lote">
`payout_batch.created`, `payout_batch.completed`, `payout_batch.cancellation_requested`, `payout_batch.cancellation_finished`
</Accordion>
<Accordion title="Remesas">
`remittance.created`, `remittance.processing`, `remittance.review`, `remittance.completed`, `remittance.failed`, `remittance.returned`
</Accordion>
<Accordion title="Reembolsos">
`refund.created`, `refund.approved`, `refund.processing`, `refund.completed`, `refund.failed`
</Accordion>
<Accordion title="Retiros">
`withdrawal.created`, `withdrawal.pending_approval`, `withdrawal.approved`, `withdrawal.submitted`, `withdrawal.completed`, `withdrawal.failed`, `withdrawal.cancelled`
</Accordion>
<Accordion title="Liquidaciones">
`settlement.created`, `settlement.processing`, `settlement.on_hold`, `settlement.completed`, `settlement.failed`, `settlement_schedule.activated`, `settlement_schedule.blocked`
</Accordion>
<Accordion title="Clientes y beneficiarios">
`customer.created`, `customer.updated`, `customer.status_changed`, `beneficiary.created`, `beneficiary.verified`
</Accordion>
<Accordion title="Página alojada">
`hosted_session.created`, `hosted_session.payment_reported`
</Accordion>
<Accordion title="Riesgo y conciliación">
`risk.review_required`, `reconciliation.exception_created`, `reconciliation.exception_resolved`
</Accordion>
<Accordion title="Webhooks">
`webhook.ping`
</Accordion>
</Accordions>

La lista puede crecer. Ignora los tipos que no conoces; no fallen tu integración.