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

# Event Types

> Catalog of webhook event Type.Action values and payload conventions.

Each delivery is a JSON object. The platform injects:

```json theme={null}
"event": "Payment.Updated"
```

where the value is `Type.Action` from the internal event enum.

## Event types (`Type`)

| Type | Meaning |
| - | - |
| `Payment` | Customer payment lifecycle |
| `Plan` | Plan / catalog definition |
| `Subscription` | Subscription lifecycle |
| `Invoice` | Invoice lifecycle |
| `Customer` | Customer records |
| `Account` | Account alerts (for example low balance / virtual account alert actions) |
| `Transaction` / `CryptoTransaction` / `OfframpTransaction` | On-chain or offramp transaction notifications when raised |
| `Org` / `MerchantContract` | Organisation or contract-level events |

## Event actions (`Action`)

Common actions:

| Action | Typical use |
| - | - |
| `Created` | Resource created |
| `Updated` | Status or field change |
| `Canceled` | Subscription or similar cancellation |
| `Overdue` | Invoice overdue |
| `Refunded` | Refund applied |
| `Settled` | Settlement-related payment stage |
| `Processed` / `Queued` / `Enabled` / `Disabled` | Operational transitions |
| `Delayed` | Delayed processing (may also notify internal ops) |
| `LowBalanceDetected` / `VirtualAccountAlert` | Account monitoring |

Exact action availability depends on the resource.

## Common merchant events

### Plan

| `event` value | When |
| - | - |
| `Plan.Created` | Plan created (one-time or recurring) |
| `Plan.Updated` | Plan field or enabled flag changed |

### Subscription

| `event` value | When |
| - | - |
| `Subscription.Created` | Subscription created |
| `Subscription.Updated` | Status changes (for example Active) |
| `Subscription.Canceled` | Subscription canceled |

### Payment

| `event` value | When |
| - | - |
| `Payment.Created` | Payment created |
| `Payment.Updated` | Payment changed. Treat `status: Succeeded` as paid. A proxy-wallet underpayment also emits this event (see below). |

Payments may include nested customer, plan, currency, and `crypto_transaction` (`hash`, `chain_id`) when relevant.

#### Partial proxy-wallet deposits

A wallet-transfer (`ProxyWallet`) payment can arrive as more than one on-chain transfer. BoomFi does not change `status` until the payment is accepted in full.

| What you receive | `status` | Meaning |
| - | - | - |
| `Payment.Created` | `RequiresAction` | Unpaid; `paid_amount` is omitted |
| `Payment.Updated` | `RequiresAction` | A deposit arrived; `paid_amount` increased and is still less than due |
| `Payment.Updated` | `Succeeded` | Accepted in full — fulfil the order |

`paid_amount` is on the webhook body and on `GET /payments` and `GET /payments/{id}` (same document):

* Decimal string in major units, same currency as `amount`
* Equal to `min(on-chain received, amount)` — overpayment is not included
* Omitted until a deposit is observed
* A later delivery with the same `paid_amount` is a retry; a larger `paid_amount` is a new partial

`proxy_wallet` is on that same document when the payment uses a proxy wallet, including each partial `Payment.Updated`. It is omitted otherwise.

| Field | Meaning |
| - | - |
| `proxy_wallet.address` | On-chain address that collects the deposit |
| `proxy_wallet.chain_id` | Chain that address is on. Same value as the payment `chain_id` |
| `proxy_wallet.token_address` | Token contract the customer pays. Omitted for the chain's native asset, or when the contract cannot be resolved from `currency` and `chain_id` |

The asset symbol is the payment `currency`. Match a partial deposit to `proxy_wallet.address`, `proxy_wallet.chain_id`, and `proxy_wallet.token_address`. Those fields are stable across `Payment.Created`, later partial `Payment.Updated` deliveries, and the `Succeeded` delivery. You can also read them from `GET /payments/{id}` if a webhook was missed.

Outstanding due:

```text theme={null}
outstanding = amount − paid_amount
```

Use decimal arithmetic, not floating point. Do not fulfil on a partial `Payment.Updated`.

### Invoice

| `event` value | When |
| - | - |
| `Invoice.Created` | Invoice opened |
| `Invoice.Overdue` | Invoice past due / dunning |

## Payload conventions

Typical fields (vary by type):

| Field | Description |
| - | - |
| `id` | Resource id |
| `org_id` / `org` | Owning organisation: always validate |
| `status` | Resource status string |
| `amount`, `currency` | Monetary fields as strings/codes |
| `paid_amount` | On-chain amount received, capped at `amount`. Omitted until a deposit is observed |
| `proxy_wallet` | Deposit address, `chain_id`, and `token_address`. Omitted when the payment has no proxy wallet. `token_address` is omitted for a native asset, or when the contract cannot be resolved |
| `customer` / `customer_id` | Payer details |
| `reference` | Merchant reference when set |
| `metadata` | Arbitrary metadata |
| `event` | `Type.Action` string |
| `payment_method` | e.g. Crypto, Deposit, ProxyWallet |
| `crypto_transaction` | On-chain hash / chain when present |

## Filtering noise

Some organisations configure notification properties so certain zero-amount proxy-wallet updates are not delivered until paid. Treat the event log as the source of truth for what was attempted.

## Full field reference

For exhaustive schemas, use the event document models in the API reference and test against sandbox deliveries.

## Next steps

* [Event History and Replay](/webhooks/event-history-and-replay)
* [Webhook Best Practices](/webhooks/best-practices)


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