# Events

Everything that happens to a charge or an invoice is recorded as an event, the same ones your webhook endpoints receive. Read them here to catch up after downtime, to reconcile without a public endpoint, or to show a customer's payment history.

## The event object

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | UUID, the same one a webhook payload carries as event_id (not its id, which names the delivery). Use it to skip events you have already handled. |
| `object` | "event" | The kind of object. |
| `type` | string | One of the event names listed under Webhooks, such as charge.paid. |
| `details` | object | What changed, for the events that record something extra; see the table below. Empty for the others. |
| `charge` | object\|null | The full charge the event is about, without its timeline, or null for invoice events. |
| `invoice` | object\|null | The full invoice the event is about, or null for charge events, including those of the invoice's own charges. |
| `created_at` | string | ISO 8601 timestamp in UTC. |

| Event | details |
| --- | --- |
| `charge.payment_detected, charge.late_payment` | txid and amount of the transfer. |
| `charge.refunded` | amount, plus txid and reason when you gave them. |
| `invoice.sent` | reminder: true when the email was a reminder. |
| `invoice.paid` | charge: the id of the charge that paid it. |
| `payout.sent, payout.confirmed` | txid, amount (what was sent) and network_fee of the payout. |

[See every event name and what it means](https://velirapay.com/docs/webhooks)

## Endpoints

- GET `/v1/events` List events, newest first. Filter with ?type=, ?charge= and ?invoice=; ?invoice= finds the invoice's own events, and the events of its charges are found with ?charge=.
- GET `/v1/events/{id}` Retrieve one event by its UUID.

```bash
curl 'https://api.velirapay.com/v1/events?type=charge.paid&per_page=100' \
  --fail-with-body --silent --show-error --max-time 30 \
  -H "Authorization: Bearer ${VELIRAPAY_API_KEY:?Set VELIRAPAY_API_KEY}" \
  -H 'Accept: application/json'
```

Webhooks are still the quickest way to hear about a payment; polling this endpoint every minute or so is the belt and braces behind them. Handle both by event id so a payment handled twice is a no-op.