> ## Documentation Index
> Fetch the complete documentation index at: https://docs.natural.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python.
> When operating Natural directly for a user, use the payments MCP at `https://mcp.natural.com`.
> When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> Use REST only for unsupported languages or when the user explicitly requests raw HTTP.
> Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it.
> For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer.
> REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code.

# Overview

> The record of what happened on your account

An event (`evt_*`) is Natural's record that something happened on your account: each one names what occurred and carries a point-in-time snapshot of the resource it describes. A webhook (`whk_*`) is the URL events are pushed to; an event is the record itself. Events are what [Webhooks](/guides/concepts/webhooks) deliver to your server. [`GET /events`](/api-reference/events/list-events) lists the same events on demand, and [`GET /events/{eventId}`](/api-reference/events/get-event) fetches one. Read them with an API key or user session holding `party.read`; to list a connected customer's events, pass `customerPartyId` and `eventType`.

## The event object

The API returns events as standard resources. The `eventType` attribute names what happened, and the resource snapshot lives at `payload.object`:

<Snippet file="api-examples/events.get.response.mdx" />

Webhook deliveries carry the same event in a flat body: there, `type` names the event and the snapshot lives at `data.object`. See [Webhooks](/guides/concepts/webhooks) for the delivery format, signature verification, and retries.

The [Event catalog](/api-reference/event-catalog) documents every event type and the full snapshot payload it carries.

For resources with a matching public GET endpoint, new event snapshots use the same resource shape: `id`, `type`, `attributes`, and any `relationships`. Money, statuses, timestamps, and missing values follow that resource's API contract. The outer event ID and event type remain separate from the resource ID and resource type. Snapshots may also include the resource's event `version`.

A snapshot records the resource at the event's time and for the party receiving it. A later GET can show newer state. Recipient payment snapshots omit sender-only diagnostics and fees; a payment from an external sender has a null sender relationship.

Wallet balances and related metadata are captured when the public event is created. Wallet snapshots include deposit instructions, with bank account and routing numbers when available. Connected subscriptions receive `wallet.created` under the customer's active connection consent; a separate `wallets.read` grant is not required for that event.

Invitation-link snapshots use the GET's masked metadata and never include the plaintext token or invitation URL.

Stored events retain the payload captured when they were created. Event history, retries, and manual redelivery can therefore contain older payload shapes. Consult the [Event catalog](/api-reference/event-catalog) for the current shape of each event, including families without a matching public GET resource.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.