Webhooks

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 and 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 and Participants Examples.

Example terminal-state payment.updated webhook (USDC payout on Ethereum, complete):


Code
{
  "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.

Last modified on August 27, 2026

Webhook Authentication

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

Example Payloads

Example terminal-state payment.updated webhook (USDC payout on Ethereum, complete):


Code
{
  "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.

Last modified on August 27, 2026