> ## Documentation Index > Fetch the complete documentation index at: https://cobo.com/payments/llms.txt > Use this file to discover all available pages before exploring further. # Events overview Cobo Payments notifies your system through webhook events. This page lists every event Cobo Payments provides, grouped by payment business. Click an event name to see its trigger conditions, fields, and samples. ## All events Events come in two kinds: * **Standard events** report the outcome of each payment business. Subscribe to the ones for the businesses you use. * **Advanced events** provide detail about the underlying on-chain transactions, such as confirmations, on-chain transaction fees, and block information. The business outcome is already reported by a standard event, so you do not need to subscribe to these unless you need that detail.
Business Event Type What it notifies you of
**Top-up** [`payment.topup.updated`](https://cobo.com/payments/payments/en/guides/events/top-up#payment-topup-updated) **Standard** A top-up's status changed: detected, in compliance screening, action required, completed, or failed.
[`payment.address.updated`](https://cobo.com/payments/payments/en/guides/events/top-up#payment-address-updated) **Standard** A payer's deposit address was replaced. Cobo also replaces addresses on its own.
[`payment.transaction.created`](https://cobo.com/payments/payments/en/guides/events/advanced#payment-transaction-created) Advanced A top-up address received a new deposit, with on-chain transaction detail.
[`payment.transaction.completed`](https://cobo.com/payments/payments/en/guides/events/advanced#payment-transaction-completed) Advanced A top-up deposit cleared compliance screening, with on-chain transaction detail.
[`payment.transaction.failed`](https://cobo.com/payments/payments/en/guides/events/advanced#payment-transaction-failed) Advanced A top-up deposit failed or was rejected (for example, did not clear compliance screening), with on-chain transaction detail.
**Orders** [`payment.order.updated`](https://cobo.com/payments/payments/en/guides/events/orders#payment-order-updated) **Standard** A pay-in order's status changed: pending, processing, paid in full, underpaid, or expired. Also sent when a deposit needs your action, fails, or arrives after the order ended.
[`payment.order.status.updated`](https://cobo.com/payments/payments/en/guides/events/advanced#payment-order-status-updated) Advanced A pay-in order's status changed, with on-chain transaction detail.
[`payment.transaction.late`](https://cobo.com/payments/payments/en/guides/events/advanced#payment-transaction-late) Advanced A screened deposit arrived after the order reached a final state.
[`payment.transaction.completed`](https://cobo.com/payments/payments/en/guides/events/advanced#payment-transaction-completed) Advanced A deposit to the order cleared compliance screening, with on-chain transaction detail.
[`payment.transaction.failed`](https://cobo.com/payments/payments/en/guides/events/advanced#payment-transaction-failed) Advanced A deposit to the order failed or was rejected (for example, did not clear compliance screening), with on-chain transaction detail.
**Unexpected deposits** [`payment.transaction.external.created`](https://cobo.com/payments/payments/en/guides/events/unexpected-deposits#payment-transaction-external-created) **Standard** An unexpected deposit is detected (transactions not within current orders/deposit plans, or deposits in unsupported tokens).
[`payment.transaction.external.completed`](https://cobo.com/payments/payments/en/guides/events/unexpected-deposits#payment-transaction-external-completed) **Standard** The unexpected deposit cleared compliance screening.
**Refunds** [`payment.refund.updated`](https://cobo.com/payments/payments/en/guides/events/refunds#payment-refund-updated) **Standard** A refund order's status changed: pending, completed, or failed.
[`payment.refund.status.updated`](https://cobo.com/payments/payments/en/guides/events/advanced#payment-refund-status-updated) Advanced A refund order's status changed, with on-chain transaction detail.
**Payouts** [`payment.payout.updated`](https://cobo.com/payments/payments/en/guides/events/payouts#payment-payout-updated) **Standard** A payout's status changed: accepted, preparing funds, transferring, completed, partially completed, failed, or returned by the receiving bank.
[`payment.payout.status.updated`](https://cobo.com/payments/payments/en/guides/events/advanced#payment-payout-status-updated) Advanced A payout's status changed, with on-chain transaction detail.
**Fiat withdrawals** [`payment.bank_withdrawal.status.updated`](https://cobo.com/payments/payments/en/guides/events/payouts#payment-bank_withdrawal-status-updated) **Standard** A fiat withdrawal from one of your virtual accounts to a bank account changed status.
**Bulk send** [`payment.bulk_send.updated`](https://cobo.com/payments/payments/en/guides/events/bulk-send#payment-bulk_send-updated) **Standard** A bulk send batch's status changed: created, validating, transferring, completed, partially completed, or failed, with amount and item-count summaries.
[`payment.bulk_send.item.updated`](https://cobo.com/payments/payments/en/guides/events/bulk-send#payment-bulk_send-item-updated) **Standard** A bulk send item's status changed: pending, processing, completed, failed, or not executed.
[`payment.bulk_send.status.updated`](https://cobo.com/payments/payments/en/guides/events/advanced#payment-bulk_send-status-updated) Advanced A bulk send batch's status changed.
[`payment.bulk_send.item.status.updated`](https://cobo.com/payments/payments/en/guides/events/advanced#payment-bulk_send-item-status-updated) Advanced A bulk send item reached a final status: `Completed`, `Failed`, or `NotExecuted`.
**Balances** [`payment.account.balance.updated`](https://cobo.com/payments/payments/en/guides/events/balances#payment-account-balance-updated) **Standard** One account's available balance moved for one token, with the balance before and after and what caused it.
## Event structure Every webhook message shares the same envelope. `event_id` uniquely identifies an event and stays the same when the event is redelivered, so use it to deduplicate. The envelope's `created_timestamp` is **when this event was created, in milliseconds**; it does not change on retries and cannot be used to order events (see [Event ordering](#event-ordering)). The `created_timestamp` and `updated_timestamp` inside `data` are **the object's own creation and last-update times, in seconds**. The envelope's `status` (`Success`, `Retrying`, `Failed`) and the `next_retry_timestamp` and `retries_left` fields that appear during retries describe delivery of this message, not your business, and can be ignored when processing. ```json theme={null} { "event_id": "8f2e919a-6a7b-4a9b-8c1a-4c0b3f5b8b2f", "url": "https://example.com/webhook", "created_timestamp": 1701396866000, "type": "payment.topup.updated", "data": { "data_type": "PaymentTopUpUpdate", ... "created_timestamp": 1701396800, "updated_timestamp": 1701396865 }, "status": "Success" } ``` | `type` | `data.data_type` | ID field | | - | - | - | | `payment.topup.updated` | `PaymentTopUpUpdate` | `transaction_id` | | `payment.order.updated` | `PaymentOrderUpdate` | `order_id` | | `payment.refund.updated` | `PaymentRefundUpdate` | `refund_id` | | `payment.payout.updated` | `PaymentPayoutUpdate` | `payout_id` | | `payment.bulk_send.updated` | `PaymentBulkSendUpdate` | `bulk_send_id` | | `payment.bulk_send.item.updated` | `PaymentBulkSendItemUpdate` | `bulk_send_item_id` | ## Rules that apply to every event ### Event ordering Cobo does not guarantee that events are delivered in the order they occur. For example, a payout moves through `Pending`, `Preparing`, `Transferring`, and `Completed`, but if one of those events fails to deliver and is retried, you may receive `Completed` before `Transferring`. Make sure your handling does not depend on the order in which events arrive. To confirm an object's latest state, call the matching query endpoint, such as [Get pay-in order information](https://cobo.com/payments/payments/en/api-references/payment/get-pay-in-order-information.md), [Get refund order information](https://cobo.com/payments/payments/en/api-references/payment/get-refund-order-information.md), [Get payout information](https://cobo.com/payments/payments/en/api-references/payment/get-payout-information.md), or [Get bulk send information](https://cobo.com/payments/payments/en/api-references/payment/get-bulk-send-information.md). ### Empty values Every field in the field tables is always present in the payload: `null` when it does not apply, `[]` for an empty array. Fields marked Optional or "Present only when…" are the exception. ### Failure reasons Events that can report a failure carry a `failed_reason` object. ```json theme={null} "failed_reason": { "code": "transaction.rejected_by_policy", "message": "..." } ``` `code` is a controlled enumeration. Use it to decide how to handle the failure. `message` is written for human operators and its wording can change, so you can display it, but do not match on it. Each business page lists the codes that can appear on that object, grouped by the response they need: [Top-up](https://cobo.com/payments/payments/en/guides/events/top-up.md#failure-reasons), [Order](https://cobo.com/payments/payments/en/guides/events/orders.md#failure-reasons), [Refund](https://cobo.com/payments/payments/en/guides/events/refunds.md#failure-reasons), [Payouts and withdrawals](https://cobo.com/payments/payments/en/guides/events/payouts.md#failure-reasons), [Bulk send](https://cobo.com/payments/payments/en/guides/events/bulk-send.md#batch-failure-reasons). ### Amounts **Unless stated otherwise, amounts carry at most two decimal places (extra digits truncated, not rounded), with trailing zeros stripped** (`100.00` is sent as `100`). | Shape | Example | Where it is used | | - | - | - | | Asset amount | `{ "amount": "100", "token_id": "ETH_USDC", "chain_id": "ETH" }` | Most amount fields. | | Asset or fiat amount | `{ "amount_type": "Crypto", "amount": "300", "token_id": "TRON_USDT", "chain_id": "TRON" }` `{ "amount_type": "Fiat", "amount": "497.5", "currency": "USD" }` | Fields that can be either crypto or fiat, such as the entries of `actual_payout_amounts`. Use `amount_type` to tell which. | | Commission fee | `{ "fee_amount": "2.5" }` | Commission charged by Cobo, **denominated in USD**. It is taken from Fee Station, whose balance is in USD. | A field whose name is plural, such as `requested_amounts`, is an array and can span several tokens. A singular field is a single object covering one asset. Never add amounts across assets. Arrays group by `token_id`, so the same token symbol on two chains is two entries. ## Set up your endpoint To set up a webhook endpoint and subscribe to events, see [Handle webhook events](https://cobo.com/payments/payments/en/developer-tools/webhook.md#handle-webhook-events).