# General All Tesser webhook events share a common envelope structure. The envelope wraps event-specific data in a consistent format so your handler can route and process events uniformly. ## Envelope Fields | Field | Type | Description | | --- | --- | --- | | `id` | string | Unique event identifier | | `type` | string | Event type in `scope.action` format (e.g. `payment.quote_created`) | | `created_at` | string | ISO 8601 timestamp of when the event was created | | `data` | object | Contains the event-specific payload under `data.object` | ## Event Type Format Event types follow the pattern **`scope.action`**. Current scopes are `payment`, `deposit`, `withdrawal`, `rebalance`, and `step`. See [Payment Updates](./payment-updates) and [Treasury Updates](./treasury-updates) for event details. ## Example Payloads The `data.object` carries the full resource for top-level events (`payment.*`, `deposit.*`, `withdrawal.*`, `rebalance.*`) and the individual step resource for `step.*` events. The top-level examples below use the terminal-state `*.updated` event, which carries the fullest payload — `desired`, `estimated`, and `actual` overlays all populated, and each step in a terminal status with its timestamps and `actual.*` filled in. The step example uses `step.completed`. The compliance arrays on the Payment example — `risk_status_reasons[]`, `participants[]`, and `provider_metadata[]` — are shown empty to keep the envelope readable. For populated examples of each, see [Outcome Examples](/overviews/wallet-risk-screening#outcome-examples) and [Participants Examples](/overviews/payment-participants#examples). Example terminal-state `payment.updated` webhook (USDC payout on Ethereum, complete): ```json { "id": "f4c8e1a3-9b76-4d2e-a058-3c5f9e1d4b27", "type": "payment.updated", "created_at": "2025-12-01T09:00:02.502Z", "data": { "object": { "id": "550e8400-e29b-41d4-a716-446655440020", "workspace_id": "550e8400-e29b-41d4-a716-446655440001", "organization_reference_id": "ref_123", "direction": "outbound", "funding_account_id": "550e8400-e29b-41d4-a716-446655440010", "desired": { "from": { "account_id": "550e8400-e29b-41d4-a716-446655440011", "amount": "1000", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "550e8400-e29b-41d4-a716-446655440012", "amount": null, "currency": "USDC", "network": "ETHEREUM" } }, "estimated": { "from": { "account_id": "550e8400-e29b-41d4-a716-446655440011", "amount": "1000", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "550e8400-e29b-41d4-a716-446655440012", "amount": "1000", "currency": "USDC", "network": "ETHEREUM" } }, "actual": { "from": { "account_id": "550e8400-e29b-41d4-a716-446655440011", "amount": "1000", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "550e8400-e29b-41d4-a716-446655440012", "amount": "1000", "currency": "USDC", "network": "ETHEREUM" } }, "risk_status": "automatically_approved", "risk_status_reasons": [], "participants": [], "provider_metadata": [ { "provider_metadata_type": "WALLET_RISK_SCREENING", "provider_metadata_key": "TRM_LABS", "provider_metadata_data": { "address": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b", "entities": [], "addressRiskIndicators": [] } } ], "risk_reviewed_by": null, "risk_reviewed_at": null, "balance_status": "reserved", "balance_reserved_at": "2025-12-01T09:00:01.000Z", "steps": [ { "id": "550e8400-e29b-41d4-a716-446655440100", "payment_id": "550e8400-e29b-41d4-a716-446655440020", "step_sequence": 1, "step_type": "transfer", "estimated": { "from": { "account_id": "550e8400-e29b-41d4-a716-446655440011", "amount": "1000", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "550e8400-e29b-41d4-a716-446655440012", "amount": "1000", "currency": "USDC", "network": "ETHEREUM" } }, "actual": { "from": { "account_id": "550e8400-e29b-41d4-a716-446655440011", "amount": "1000", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "550e8400-e29b-41d4-a716-446655440012", "amount": "1000", "currency": "USDC", "network": "ETHEREUM" } }, "transaction_hash": "0xd65dc6bf6dcc ... e877f7be", "unsigned_transaction": null, "fees": [ { "fee_amount": "0.01", "fee_currency": "USDC", "fee_type": "gas", "fee_metadata": {} } ], "provider_key": "circle_mint", "status": "completed", "status_reasons": [], "created_at": "2025-12-01T09:00:00.040Z", "updated_at": "2025-12-01T09:00:02.500Z", "submitted_at": "2025-12-01T09:00:01.200Z", "confirmed_at": "2025-12-01T09:00:01.800Z", "completed_at": "2025-12-01T09:00:02.500Z", "failed_at": null } ], "created_at": "2025-12-01T09:00:00.000Z", "updated_at": "2025-12-01T09:00:02.500Z", "expires_at": "2025-12-01T23:59:59.999Z" } } } ``` **Inbound variant.** The example above is an outbound payout. Inbound payments use the same envelope and the same Payment resource, with these differences: | Field | Outbound | Inbound | | --- | --- | --- | | `direction` | `outbound` | `inbound` | | `funding_account_id` | the account funding the payout | `null` | | `desired.*` | echoes what you requested | all `null` — you never requested the payment | | `estimated.*` | populated at planning (`payment.quote_created`) | populated when Tesser records the on-chain transaction (`payment.created`) | | `expires_at` | end of the quote and funding window | `null` | | `steps[]` | one entry per planned leg | exactly one, created in `confirmed` status | | `steps[].provider_key` | `circle_mint`, `openfx`, or `turnkey` | `null` — the external sender signed and broadcast the transaction | For full inbound payloads at each stage, see [Receive an Inbound Payment to a Wallet](/how-tos/receive-an-inbound-payment-to-a-wallet). Example terminal-state `deposit.updated` webhook (USD deposit on-ramped to a USDC ledger at Circle, complete): ```json { "id": "e2c6d8b1-4f7a-4e93-9b8d-2a5c7f3e1d4b", "type": "deposit.updated", "created_at": "2025-12-02T14:30:00.700Z", "data": { "object": { "id": "1c8e4a6f-9b2d-4f53-a0e7-5d3c1b9f2a8e", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": null, "direction": "inbound", "desired": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": null, "currency": "USDC", "network": null } }, "estimated": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USDC", "network": null } }, "actual": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USDC", "network": null } }, "steps": [ { "id": "8a4f2c1e-9b6d-4e35-b7a0-3c5d1e9f2b8a", "deposit_id": "1c8e4a6f-9b2d-4f53-a0e7-5d3c1b9f2a8e", "step_sequence": 1, "step_type": "transfer", "estimated": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "a81bc1f4-7e3d-4926-b04f-3d2e8a9c5f17", "amount": "1000", "currency": "USD", "network": null } }, "actual": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "a81bc1f4-7e3d-4926-b04f-3d2e8a9c5f17", "amount": "1000", "currency": "USD", "network": null } }, "fees": [], "transaction_hash": null, "provider_key": "circle_mint", "status": "completed", "status_reasons": [], "created_at": "2025-12-01T10:00:00.000Z", "updated_at": "2025-12-02T14:25:00.500Z", "submitted_at": null, "confirmed_at": "2025-12-02T14:25:00.400Z", "completed_at": "2025-12-02T14:25:00.500Z", "failed_at": null }, { "id": "3b7e9d2f-1c4a-4f68-a5b0-6e8c1d3f9a2b", "deposit_id": "1c8e4a6f-9b2d-4f53-a0e7-5d3c1b9f2a8e", "step_sequence": 2, "step_type": "transfer", "estimated": { "from": { "account_id": "a81bc1f4-7e3d-4926-b04f-3d2e8a9c5f17", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USDC", "network": null } }, "actual": { "from": { "account_id": "a81bc1f4-7e3d-4926-b04f-3d2e8a9c5f17", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USDC", "network": null } }, "fees": [], "transaction_hash": null, "provider_key": "circle_mint", "status": "completed", "status_reasons": [], "created_at": "2025-12-01T10:00:00.000Z", "updated_at": "2025-12-02T14:30:00.500Z", "submitted_at": null, "confirmed_at": "2025-12-02T14:30:00.400Z", "completed_at": "2025-12-02T14:30:00.500Z", "failed_at": null } ], "created_at": "2025-12-01T10:00:00.000Z", "updated_at": "2025-12-02T14:30:00.700Z", "expires_at": "2025-12-01T14:00:00.000Z" } } } ``` Example terminal-state `withdrawal.updated` webhook (USDC off-ramped via Circle redemption to a USD bank account; swap step + transfer step, complete): ```json { "id": "a3d9e1f2-4b6c-4e58-8d2a-5f7b9c1d3e4f", "type": "withdrawal.updated", "created_at": "2025-12-01T11:30:00.700Z", "data": { "object": { "id": "9b4d7c2e-5f8a-43b1-ae6d-2f7c9e3b1a8d", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": null, "direction": "outbound", "balance_status": "reserved", "balance_reserved_at": "2025-12-01T10:00:01.000Z", "desired": { "from": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USDC", "network": null }, "to": { "account_id": "c4a7e9b3-5d2f-4e8a-b6c1-9f3a7d2e8b4f", "amount": null, "currency": "USD", "network": null } }, "estimated": { "from": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USDC", "network": null }, "to": { "account_id": "c4a7e9b3-5d2f-4e8a-b6c1-9f3a7d2e8b4f", "amount": "1000", "currency": "USD", "network": null } }, "actual": { "from": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USDC", "network": null }, "to": { "account_id": "c4a7e9b3-5d2f-4e8a-b6c1-9f3a7d2e8b4f", "amount": "1000", "currency": "USD", "network": null } }, "steps": [ { "id": "3a8e2f5c-9d4b-4f73-a2c0-6b1d3e9f7c4a", "withdrawal_id": "9b4d7c2e-5f8a-43b1-ae6d-2f7c9e3b1a8d", "step_sequence": 1, "step_type": "swap", "estimated": { "from": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USDC", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USD", "network": null } }, "actual": { "from": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USDC", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USD", "network": null } }, "fees": [], "transaction_hash": null, "unsigned_transaction": null, "provider_key": "circle_mint", "status": "completed", "status_reasons": [], "created_at": "2025-12-01T10:00:00.000Z", "updated_at": "2025-12-01T10:02:00.500Z", "submitted_at": "2025-12-01T10:02:00.300Z", "confirmed_at": "2025-12-01T10:02:00.400Z", "completed_at": "2025-12-01T10:02:00.500Z", "failed_at": null }, { "id": "6b9d4f2c-3e8a-4571-b0c6-8d2f1e9b4a3c", "withdrawal_id": "9b4d7c2e-5f8a-43b1-ae6d-2f7c9e3b1a8d", "step_sequence": 2, "step_type": "transfer", "estimated": { "from": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "c4a7e9b3-5d2f-4e8a-b6c1-9f3a7d2e8b4f", "amount": "1000", "currency": "USD", "network": null } }, "actual": { "from": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "c4a7e9b3-5d2f-4e8a-b6c1-9f3a7d2e8b4f", "amount": "1000", "currency": "USD", "network": null } }, "fees": [], "transaction_hash": null, "unsigned_transaction": null, "provider_key": "circle_mint", "status": "completed", "status_reasons": [], "created_at": "2025-12-01T10:00:00.000Z", "updated_at": "2025-12-01T11:30:00.500Z", "submitted_at": "2025-12-01T10:02:00.700Z", "confirmed_at": "2025-12-01T10:02:00.800Z", "completed_at": "2025-12-01T11:30:00.500Z", "failed_at": null } ], "created_at": "2025-12-01T10:00:00.000Z", "updated_at": "2025-12-01T11:30:00.700Z", "expires_at": "2025-12-01T14:00:00.000Z" } } } ``` Example terminal-state `rebalance.updated` webhook (USDC rebalanced between two Circle ledger accounts, complete): ```json { "id": "d2e4f6a8-1c3b-4e57-9a8d-2c4e6f8a0b1d", "type": "rebalance.updated", "created_at": "2025-12-01T10:05:00.700Z", "data": { "object": { "id": "9a1b2c3d-4e5f-4789-a0bc-1234567890ab", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": null, "direction": "rebalance", "balance_status": "reserved", "balance_reserved_at": "2025-12-01T10:00:01.000Z", "desired": { "from": { "account_id": "c1c1e7d1-1aaa-4f01-b001-aaaa11110001", "amount": "1000", "currency": "USDC", "network": null }, "to": { "account_id": "c2c2f8d2-2bbb-4f02-b002-bbbb22220002", "amount": null, "currency": "USDC", "network": null } }, "estimated": { "from": { "account_id": "c1c1e7d1-1aaa-4f01-b001-aaaa11110001", "amount": "1000", "currency": "USDC", "network": null }, "to": { "account_id": "c2c2f8d2-2bbb-4f02-b002-bbbb22220002", "amount": "1000", "currency": "USDC", "network": null } }, "actual": { "from": { "account_id": "c1c1e7d1-1aaa-4f01-b001-aaaa11110001", "amount": "1000", "currency": "USDC", "network": null }, "to": { "account_id": "c2c2f8d2-2bbb-4f02-b002-bbbb22220002", "amount": "1000", "currency": "USDC", "network": null } }, "steps": [ { "id": "8a4f2c1e-9b6d-4e35-b7a0-3c5d1e9f2b8a", "rebalance_id": "9a1b2c3d-4e5f-4789-a0bc-1234567890ab", "step_sequence": 1, "step_type": "transfer", "estimated": { "from": { "account_id": "c1c1e7d1-1aaa-4f01-b001-aaaa11110001", "amount": "1000", "currency": "USDC", "network": null }, "to": { "account_id": "c2c2f8d2-2bbb-4f02-b002-bbbb22220002", "amount": "1000", "currency": "USDC", "network": null } }, "actual": { "from": { "account_id": "c1c1e7d1-1aaa-4f01-b001-aaaa11110001", "amount": "1000", "currency": "USDC", "network": null }, "to": { "account_id": "c2c2f8d2-2bbb-4f02-b002-bbbb22220002", "amount": "1000", "currency": "USDC", "network": null } }, "fees": [], "transaction_hash": null, "unsigned_transaction": null, "provider_key": "circle_mint", "status": "completed", "status_reasons": [], "created_at": "2025-12-01T10:00:00.000Z", "updated_at": "2025-12-01T10:05:00.500Z", "submitted_at": "2025-12-01T10:05:00.300Z", "confirmed_at": "2025-12-01T10:05:00.400Z", "completed_at": "2025-12-01T10:05:00.500Z", "failed_at": null } ], "created_at": "2025-12-01T10:00:00.000Z", "updated_at": "2025-12-01T10:05:00.700Z", "expires_at": "2025-12-01T14:00:00.000Z" } } } ``` Example `step.completed` webhook (Circle-internal transfer step on a rebalance): ```json { "id": "f1e2d3c4-5b6a-4798-8e0d-3f4a5b6c7d8e", "type": "step.completed", "created_at": "2025-12-01T10:05:00.500Z", "data": { "object": { "id": "8a4f2c1e-9b6d-4e35-b7a0-3c5d1e9f2b8a", "rebalance_id": "9a1b2c3d-4e5f-4789-a0bc-1234567890ab", "step_sequence": 1, "step_type": "transfer", "estimated": { "from": { "account_id": "c1c1e7d1-1aaa-4f01-b001-aaaa11110001", "amount": "1000", "currency": "USDC", "network": null }, "to": { "account_id": "c2c2f8d2-2bbb-4f02-b002-bbbb22220002", "amount": "1000", "currency": "USDC", "network": null } }, "actual": { "from": { "account_id": "c1c1e7d1-1aaa-4f01-b001-aaaa11110001", "amount": "1000", "currency": "USDC", "network": null }, "to": { "account_id": "c2c2f8d2-2bbb-4f02-b002-bbbb22220002", "amount": "1000", "currency": "USDC", "network": null } }, "fees": [], "transaction_hash": null, "unsigned_transaction": null, "provider_key": "circle_mint", "status": "completed", "status_reasons": [], "created_at": "2025-12-01T10:00:00.000Z", "updated_at": "2025-12-01T10:05:00.500Z", "submitted_at": "2025-12-01T10:05:00.300Z", "confirmed_at": "2025-12-01T10:05:00.400Z", "completed_at": "2025-12-01T10:05:00.500Z", "failed_at": null } } } ```