Payloads

Every webhook body is a versioned envelope. The data object is the same merchant-facing resource contract returned by the corresponding status API, so your handler can apply a complete snapshot instead of merging partial deltas.

Envelope

Field	Type	Contract
event_id	string	Stable prefixed ID (evt_…), identical to X-Webhook-Id and unchanged across retries and replay
event_type	string	One value from the event catalog
version	integer	Payload schema version. The current version is 1
occurred_at	Unix seconds	Time of the resource transition; unlike the delivery timestamp, it does not change on retry
data	object	Full invoice or withdrawal resource snapshot for this event

Store event_id, event_type, version, and the raw body before starting expensive work. Reject a schema version your integration does not support rather than guessing its shape.

Invoice payload

Example: invoice.paid.

{
  "event_id": "evt_J7EEYeL9pZJukfj2c5OQ44",
  "event_type": "invoice.paid",
  "version": 1,
  "occurred_at": 1739281200,
  "data": {
    "invoice_id": "inv_5CcyDYmMUGtzYL10q0Iimr",
    "project_id": "prj_xFukZuAJZR06pLVBh3uwzv",
    "status": "paid",
    "is_final": true,
    "is_test": false,
    "payment_url": "https://checkout.paymos.io/invoice/inv_5CcyDYmMUGtzYL10q0Iimr",
    "order": {
      "external_id": "order-12345",
      "client_id": "customer-67890",
      "amount": "100.00",
      "currency": "USD"
    },
    "payment": {
      "currency": "USDT",
      "network": "TRC20",
      "chain_id": 728126428,
      "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "expected": "50.00",
      "address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
      "exchange_rate": "2.00",
      "paid": "50.00",
      "remaining": "0",
      "fee": "0.50",
      "net": "49.50",
      "transfers": [
        {
          "tx_hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
          "amount": "50.00",
          "status": "confirmed",
          "created_at": 1739281020,
          "confirmed_at": 1739281200,
          "required_confirmations": 19,
          "estimated_confirmation_at": 1739281080,
          "explorer_url": "https://tronscan.org/#/transaction/abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
        }
      ]
    },
    "expires_at": 1739284200,
    "completed_at": 1739281200,
    "created_at": 1739277600,
    "updated_at": 1739281200
  }
}

Invoice data follows the Get Invoice response. Fields that do not exist yet for the current state are null or omitted by the JSON contract; use status and is_final as the state authority.

Withdrawal payload

Example: withdrawal.completed.

{
  "event_id": "evt_CbYeOgBp9Kt2U3j74fxxLl",
  "event_type": "withdrawal.completed",
  "version": 1,
  "occurred_at": 1739281200,
  "data": {
    "withdrawal_id": "wdr_7K2M9P4Q8R1X5Z3A0bC2dE",
    "external_order_id": "payout-12345",
    "status": "completed",
    "is_final": true,
    "is_test": false,
    "amount": "25.00",
    "fee": "0.50",
    "currency": "USDT",
    "network": "TRC20",
    "destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
    "tx_hash": "7f8a9b0c1d2e3f4a5b6c7d8e9f00112233445566778899aabbccddeeff001122",
    "explorer_url": "https://tronscan.org/#/transaction/7f8a9b0c1d2e3f4a5b6c7d8e9f00112233445566778899aabbccddeeff001122",
    "created_at": 1739277600,
    "completed_at": 1739281200
  }
}

Withdrawal data follows the Get Withdrawal response. tx_hash and explorer_url are populated when a tracked on-chain transaction is available; they are not a substitute for status.

Compatibility

• Additive fields may appear without a version change. Ignore fields your handler does not use.
• Existing field meanings do not change within one payload version.
• Treat identifiers and decimal amounts as strings. Do not parse prefixed IDs as UUIDs or money as binary floating point.
• Verify the signature against the raw bytes before parsing JSON. Re-serializing the object changes the signed input.