Skip to main content

Webhook Messages

Overview​

TPX communicates with partners through webhook messages sent to your configured endpoint. This document describes the webhook message structure, types, and handling requirements.

Message Structure​

All TPX webhook messages follow a consistent JSON structure:

{
  "msg_type": "BID_REQUEST",
  "msg_id": "123e4567-e89b-12d3-a456-426614174000",
  "sent_at": 1736614800,
  "source_id": "tradepost_auction_service",
  "destination_id": "partner_acme",
  "payload": {
    "conversation_id": "...",
    "reference_type": "INSTANT_CASH_OFFER",
    "reference_id": "..."
  }
}

Common Fields​

  • msg_type: Type of message (see Message Types below)
  • msg_id: Unique identifier for this message (UUID)
  • sent_at: Unix timestamp when message was sent
  • source_id: Identifier of the sending system (e.g., "tradepost_auction_service")
  • destination_id: Identifier of the receiving system (e.g., "partner_yourname")
  • payload: Message-specific data

Field Naming Convention: Webhook messages use snake_case for all field names (e.g., conversation_id, bid_amount_cents), while GraphQL uses camelCase. This follows industry standards:

  • Process webhook fields exactly as they arrive in snake_case
  • No transformation needed - we handle any necessary conversions
  • This consistent pattern applies to all TPX messages

Message Types​

TPX currently supports 11 webhook message types:

Consistent Asset Payload: All webhook messages include the same asset information structure:

  • asset_type: Type identifier (TICKET, SEALED_TCG)
  • external_ids: Platform identifiers for the asset
  • asset_details: Asset-level information (event details for tickets, set details for sealed TCG)
  • config_details: Configuration-level information (event config for tickets, product config for sealed TCG)
  • item_details: Item-specific information (section/row/seats for tickets, condition/quantity for sealed TCG)

This consistency allows you to process, reconcile, and track items across all webhook types without referencing previous messages. See Asset Types for field details per asset type.

note

Examples below show TICKET payloads. The message structure is identical for all asset types — only the fields within external_ids, asset_details, config_details, and item_details vary. See Ticket and Sealed TCG for asset-specific field reference.

1. BID_REQUEST​

Sent when a new auction starts and partners can submit bids for an instant cash offer.

  • current_offer_cents_per_unit (optional): When present, indicates an existing offer has already been matched for this item at the specified price per unit (in cents). Use this as a reference point — to win the auction, your bid must exceed this amount. When null, no existing offer has been matched.
{
  "msg_type": "BID_REQUEST",
  "msg_id": "550e8400-e29b-41d4-a716-446655440000",
  "sent_at": 1736614800,
  "source_id": "tradepost_auction_service",
  "destination_id": "partner_acme",
  "payload": {
    "conversation_id": "conv_123",
    "reference_type": "INSTANT_CASH_OFFER",
    "reference_id": "ico_456",
    "current_offer_cents_per_unit": 15000,
    "asset_type": "TICKET",
    "external_ids": {
      "SEATGEEK": "17346315",
      "TICKETMASTER": "vvG1YZ4bJalaRJ",
      "STUBHUB": "123456789",
      "VIVID_SEATS": "5470600"
    },
    "asset_details": {
      "id": "3b9a0f8e-b6c8-4f79-89a5-2ed522bf9740",
      "event_name": "Taylor Swift | The Eras Tour",
      "venue_name": "Hard Rock Stadium",
      "event_date_utc": "2025-10-18T19:00:00Z",
      "event_date_local": "2025-10-18T15:00:00"
    },
    "config_details": {
      "id": "741335d5-c78c-414c-9f46-5b3577beea5f",
      "event_type": "PRIMARY",
      "event_name": "Taylor Swift | The Eras Tour",
      "event_date_utc": "2025-10-18T19:00:00Z",
      "event_date_local": "2025-10-18T15:00:00"
    },
    "item_details": {
      "key_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "key_ids": ["a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d", "b2c3d4e5-f6a7-4b5c-9d0e-1f2a3b4c5d6e"],
      "fair_values": [],
      "section": "Floor B",
      "row": "10",
      "seat_numbers": ["1", "2"],
      "quantity": 2,
      "ticket_type": "MOBILE"
    }
  }
}

2. BID_OUTBID​

Sent in real-time when your bid is outbid by another partner during an active auction.

{
  "msg_type": "BID_OUTBID",
  "msg_id": "c887a819-d059-43c6-8aed-d6632ae51bbd",
  "sent_at": 1765922164,
  "source_id": "tradepost_auction_service",
  "destination_id": "partner_acme",
  "payload": {
    "conversation_id": "3f681538-41d9-5920-857d-eb942d9a7fe9",
    "bid_id": "795d6282-7ff8-48bf-b10b-a387c3333f28",
    "bid_external_reference_id": "liberty-mutual-music-city-bowl-1765922162",
    "conditional_bid_id": "6275799c-1377-474f-b1f4-1b5f114bf926",
    "conditional_bid_external_id": "liberty-mutual-music-city-bowl-1765922162",
    "outbid_at": 1765922164,
    "highest_bid_cents": 12560,
    "asset_type": "TICKET",
    "external_ids": {
      "STUBHUB": "158460140",
      "GAMETIME": "68408e9d1b4a78e1658c7b09",
      "SEATGEEK": "17657618",
      "TICKPICK": "7198491",
      "AUTOMATIQ": "N74DD42",
      "VIVID_SEATS": "5797954"
    },
    "asset_details": {
      "id": "a445162f-29e0-4e37-93d1-6f6a4c163f6a",
      "event_name": "Liberty Mutual Music City Bowl",
      "venue_name": "Nissan Stadium",
      "venue_city": "Nashville",
      "venue_state": "TN",
      "venue_country": "US",
      "event_date_utc": "2025-12-30T22:30:00+00:00",
      "event_date_local": "2025-12-30T16:30:00+00:00",
      "categories": ["Sports", "Football", "NCAA Football"],
      "primary_category": "Sports",
      "subject_names": ["Liberty Mutual Music City Bowl"]
    },
    "config_details": {
      "id": "db30742a-fce5-4677-bfa5-06c1c78499e1",
      "event_type": "PRIMARY",
      "event_name": "Liberty Mutual Music City Bowl",
      "event_date_utc": "2025-12-30T22:30:00+00:00",
      "event_date_local": "2025-12-30T16:30:00"
    },
    "item_details": {
      "key_id": "732c84a2-9d8a-41c6-af02-2bf85737c173",
      "section": "105",
      "row": "aa",
      "seat_numbers": ["1"],
      "quantity": 1
    }
  }
}

Outbid Fields:

  • bid_id: Your bid ID that was outbid
  • bid_external_reference_id: Your tracking ID for the bid
  • conditional_bid_id: If bid came from conditional bid (null for on-demand bids)
  • conditional_bid_external_id: Your conditional bid tracking ID (if applicable)
  • outbid_at: Unix timestamp when you were outbid
  • highest_bid_cents: The new highest bid amount that outbid you

Use Cases:

  • Real-time notification to increase bid before auction closes
  • Automatic re-bidding logic in your systems
  • Tracking competitive dynamics across auctions
  • Alerting your team when losing valuable inventory

Note: This is sent immediately when outbid occurs. You can submit a higher bid via createLiveBid if the auction is still active.

3. AUCTION_RESULT​

Sent when an auction concludes to notify partners of the outcome.

Single Winner (No Split):

{
  "msg_type": "AUCTION_RESULT",
  "msg_id": "660e8400-e29b-41d4-a716-446655440001",
  "sent_at": 1736615400,
  "source_id": "tradepost_auction_service",
  "destination_id": "partner_acme",
  "payload": {
    "conversation_id": "conv_123",
    "result": "WON",
    "reference_type": "INSTANT_CASH_OFFER",
    "reference_id": "ico_456",
    "winning_price_cents_per_unit": 11000,
    "your_price_cents": 11000,
    "quantity_won": 4,
    "is_partial_win": false,
    "external_reference_id": "partner-bid-123",
    "asset_type": "TICKET",
    "external_ids": {
      "SEATGEEK": "17346315",
      "TICKETMASTER": "vvG1YZ4bJalaRJ",
      "STUBHUB": "123456789",
      "VIVID_SEATS": "5470600"
    },
    "asset_details": {
      "id": "3b9a0f8e-b6c8-4f79-89a5-2ed522bf9740",
      "event_name": "Taylor Swift | The Eras Tour",
      "venue_name": "Hard Rock Stadium",
      "event_date_utc": "2025-10-18T19:00:00Z",
      "event_date_local": "2025-10-18T15:00:00"
    },
    "config_details": {
      "id": "741335d5-c78c-414c-9f46-5b3577beea5f",
      "event_type": "PRIMARY",
      "event_name": "Taylor Swift | The Eras Tour",
      "event_date_utc": "2025-10-18T19:00:00Z",
      "event_date_local": "2025-10-18T15:00:00"
    },
    "item_details": {
      "key_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "section": "Floor B",
      "row": "10",
      "seat_numbers": ["1", "2", "3", "4"],
      "quantity": 4,
      "ticket_type": "MOBILE"
    }
  }
}

Split Winner (Multiple Partners):

{
  "msg_type": "AUCTION_RESULT",
  "msg_id": "660e8400-e29b-41d4-a716-446655440002",
  "sent_at": 1736615400,
  "source_id": "tradepost_auction_service",
  "destination_id": "partner_acme",
  "payload": {
    "conversation_id": "conv_123",
    "result": "WON",
    "reference_type": "INSTANT_CASH_OFFER",
    "reference_id": "ico_456",
    "winning_price_cents_per_unit": 11000,
    "your_price_cents": 11000,
    "quantity_won": 2,
    "is_partial_win": true,
    "total_quantity": 4,
    "external_reference_id": "partner-bid-123",
    "asset_type": "TICKET",
    "external_ids": {...},
    "asset_details": {...},
    "config_details": {...},
    "item_details": {
      "key_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "fair_value": null,
      "section": "Floor B",
      "row": "10",
      "seat_numbers": ["1", "2"],
      "quantity": 2,
      "ticket_type": "MOBILE"
    }
  }
}

Lost Auction:

{
  "msg_type": "AUCTION_RESULT",
  "msg_id": "660e8400-e29b-41d4-a716-446655440003",
  "sent_at": 1736615400,
  "source_id": "tradepost_auction_service",
  "destination_id": "partner_acme",
  "payload": {
    "conversation_id": "conv_123",
    "result": "LOST",
    "reference_type": "INSTANT_CASH_OFFER",
    "reference_id": "ico_456",
    "winning_price_cents_per_unit": 11000,
    "your_price_cents": 10000,
    "external_reference_id": "partner-bid-123",
    "asset_type": "TICKET",
    "external_ids": {...},
    "asset_details": {...},
    "config_details": {...},
    "item_details": {...}
  }
}

Result Fields:

  • result: Auction outcome (WON or LOST)
  • winning_price_cents_per_unit: The winning bid price per unit in cents
  • your_price_cents: Your bid amount
  • quantity_won: Number of items you won (only for WON)
  • is_partial_win: true if the offer was split across multiple partners (only for WON)
  • total_quantity: Original quantity before splitting (only present when is_partial_win is true)
  • asset_type, external_ids, asset_details, config_details, item_details: Full asset information (same structure as BID_REQUEST)

Important Notes:

  • When is_partial_win is true, you won a portion of the total quantity. Other partners won the remaining items. You will only receive and pay for quantity_won items.
  • The item_details.quantity field reflects the quantity you won (matches quantity_won), not the original total quantity.
  • Asset details are included so you can process the result without referencing the original BID_REQUEST.

4. CONDITIONAL_BID_APPLIED​

Sent when a conditional bid is automatically applied to an auction.

{
  "msg_type": "CONDITIONAL_BID_APPLIED",
  "msg_id": "770e8400-e29b-41d4-a716-446655440002",
  "sent_at": 1736616000,
  "source_id": "tradepost_auction_service",
  "destination_id": "partner_acme",
  "payload": {
    "conversation_id": "conv_123",
    "external_reference_id": "partner_ref_789",
    "ico_id": "ico_456",
    "ico_item_id": "ico_item_789",
    "listing_id": "listing_999",
    "reference_type": "INSTANT_CASH_OFFER",
    "reference_id": "ico_456",
    "bid_amount_cents": 10500,
    "applied_at": 1736616000,
    "asset_type": "TICKET",
    "external_ids": {...},
    "asset_details": {...},
    "config_details": {...},
    "item_details": {...}
  }
}

Fields:

  • ico_id: ID of the instant cash offer this conditional bid was applied to
  • ico_item_id: ID of the specific instant cash offer item
  • listing_id: Deprecated — will be removed in a future release. Use ico_id instead.

Note: This message includes the same asset_type, external_ids, asset_details, config_details, and item_details structure as BID_REQUEST so you can verify the conditional bid was applied to the correct auction.

5. CONDITIONAL_BID_STATUS_CHANGE​

Sent when a conditional bid status changes due to risk control (e.g., placed ON_HOLD or resumed).

{
  "msg_type": "CONDITIONAL_BID_STATUS_CHANGE",
  "msg_id": "770e8400-e29b-41d4-a716-446655440003",
  "sent_at": 1736616000,
  "source_id": "tradepost_auction_service",
  "destination_id": "partner_acme",
  "payload": {
    "conditional_bid_id": "550e8400-e29b-41d4-a716-446655440000",
    "external_reference_id": "partner-cb-001",
    "old_status": "NOT_FILLED",
    "new_status": "ON_HOLD",
    "reason": "Aggregate risk $7,500.00 exceeds threshold",
    "external_identifiers": {
      "TICKETMASTER": "vvG1YZ4bJalaRJ",
      "SEATGEEK": "6234567"
    },
    "status_changed_at": 1736616000
  }
}

Status Change Fields:

  • conditional_bid_id: Tradepost internal ID of the conditional bid
  • external_reference_id: Your tracking ID for the conditional bid
  • old_status: Previous status before change
  • new_status: New status after change
  • reason: Human-readable explanation for status change
  • external_identifiers: Platform IDs associated with this bid
  • status_changed_at: Unix timestamp when status changed

Common Scenarios:

  • Risk Triggered: NOT_FILLED → ON_HOLD (aggregate risk exceeds $5,000)
  • Mapping Verified: ON_HOLD → NOT_FILLED (bid automatically resumed)
  • Mapping Rejected: ON_HOLD → CANCELLED (bid cancelled due to invalid mapping)
  • Bid Expired: NOT_FILLED/PARTIALLY_FILLED → EXPIRED (bid reached its expires_at deadline)

Partner Action: Monitor these webhooks to track bid lifecycle. Risk-held bids automatically resume when mappings are verified. Expired bids require creating a new conditional bid if you want to continue bidding.

6. CONDITIONAL_BID_EXPIRING_SOON​

Advisory notification sent when a conditional bid is approaching its expiration deadline. This is not a status change — the bid remains active. It gives partners advance warning to take action (renew, cancel, or let expire).

{
  "msg_type": "CONDITIONAL_BID_EXPIRING_SOON",
  "msg_id": "880e8400-e29b-41d4-a716-446655440010",
  "sent_at": 1736616000,
  "source_id": "tradepost_auction_service",
  "destination_id": "partner_acme",
  "payload": {
    "conditional_bid_id": "550e8400-e29b-41d4-a716-446655440000",
    "external_reference_id": "partner-cb-001",
    "current_status": "NOT_FILLED",
    "expires_at": 1736619600,
    "seconds_remaining": 3600
  }
}

Fields:

  • conditional_bid_id: Tradepost internal ID of the conditional bid
  • external_reference_id: Your tracking ID for the conditional bid
  • current_status: Current bid status (NOT_FILLED or PARTIALLY_FILLED)
  • expires_at: Unix timestamp when the bid will expire
  • seconds_remaining: Seconds until expiration at the time the notification was sent

Behavior:

  • Sent once per bid per expiration deadline (if expires_at is extended, a new notification is sent as the new deadline approaches)
  • Default threshold: 1 hour before expiration
  • The bid remains active and eligible for matching until it actually expires

Partner Action: Use this as a signal to renew the bid (update expires_at) or adjust your bidding strategy before the bid expires.

7. INSTANT_CASH_OFFER_STATUS_CHANGE​

Sent when an instant cash offer status changes (ACCEPTED, DECLINED, or EXPIRED).

ACCEPTED Example:

{
  "msg_type": "INSTANT_CASH_OFFER_STATUS_CHANGE",
  "msg_id": "6885f717-5594-4003-be35-d66ee66a36f5",
  "sent_at": 1749607405,
  "source_id": "tradepost_auction_service",
  "destination_id": "partner_cheesecake",
  "payload": {
    "conversation_id": "70f60410-ffed-4f39-91ac-180395c995b7",
    "reference_type": "INSTANT_CASH_OFFER",
    "reference_id": "cc36dedc-def3-4504-ba53-b33b5715c63e",
    "status": "ACCEPTED",
    "status_changed_at": 1749607405,
    "external_reference_id": "partner_ref_789",
    "fulfillment_info": {
      "order_id": "550e8400-e29b-41d4-a716-446655440000",
      "transfer_id": "660e8400-e29b-41d4-a716-446655440001",
      "transfer_method": "DIGITAL",
      "seller_transfer_deadline": 1749609205,
      "primary_ticket_manager": "TICKETMASTER"
    },
    "asset_type": "TICKET",
    "external_ids": {...},
    "asset_details": {...},
    "config_details": {...},
    "item_details": {...}
  }
}

DECLINED/EXPIRED Example:

{
  "msg_type": "INSTANT_CASH_OFFER_STATUS_CHANGE",
  "msg_id": "7895f717-5594-4003-be35-d66ee66a36f6",
  "sent_at": 1749608000,
  "source_id": "tradepost_auction_service",
  "destination_id": "partner_cheesecake",
  "payload": {
    "conversation_id": "70f60410-ffed-4f39-91ac-180395c995b7",
    "reference_type": "INSTANT_CASH_OFFER",
    "reference_id": "cc36dedc-def3-4504-ba53-b33b5715c63e",
    "status": "DECLINED",
    "status_changed_at": 1749608000,
    "external_reference_id": "partner_ref_789",
    "asset_type": "TICKET",
    "external_ids": {...},
    "asset_details": {...},
    "config_details": {...},
    "item_details": {...}
  }
}

Status Values:

  • ACCEPTED: Seller accepted the offer - prepare to receive items
  • DECLINED: Seller declined the offer - no action needed
  • EXPIRED: Offer expired without seller response - no action needed

Field Details:

  • status: Current status of the ICO
  • external_reference_id: Your tracking ID (from conditional bid or on-demand bid)
  • status_changed_at: When the status transition occurred
  • fulfillment_info: Only present when status is ACCEPTED - contains order, transfer, and logistics details:
    • order_id: Order ID for your tracking and reconciliation
    • transfer_id: Transfer ID for tracking item delivery
    • transfer_method: DIGITAL or PHYSICAL - determines the transfer workflow
    • seller_transfer_deadline: Unix timestamp when seller must complete transfer (30 minutes for digital, longer for physical). Use this to monitor transfer progress.
    • primary_ticket_manager: Primary platform where tickets originate (e.g., TICKETMASTER, AXS, EVENTBRITE, STUBHUB). Defaults to NOT_SPECIFIED for non-ticket asset types or unknown sources.

Payment Timing: You are not charged when this webhook is sent. Payment occurs when you receive the TRANSFER_CONFIRMATION_RECEIVED webhook, after the transfer is confirmed. See Payments for complete details.

Transfer Deadline: For DIGITAL transfers, the seller has 30 minutes from acceptance to complete the transfer. Use seller_transfer_deadline to monitor and enforce this deadline in your systems.

8. TRANSFER_CONFIRMATION_RECEIVED​

Sent when the transfer is confirmed — either automatically by Tradepost or when you call processPartnerTransfer with action: CONFIRMED.

{
  "msg_type": "TRANSFER_CONFIRMATION_RECEIVED",
  "msg_id": "880e8400-e29b-41d4-a716-446655440003",
  "sent_at": 1736618000,
  "source_id": "tradepost_transfer_service",
  "destination_id": "partner_acme",
  "payload": {
    "conversation_id": "conv_123",
    "reference_type": "INSTANT_CASH_OFFER",
    "reference_id": "ico_456",
    "transfer_info": {
      "transfer_id": "xfer_123456",
      "transfer_type": "DIGITAL",
      "transfer_method": "EMAIL_TRANSFER",
      "tracking_info": "TICKET-TRANSFER-XYZ123",
      "transfer_status": "completed"
    },
    "payment_details": {
      "winning_bid_amount_cents": 11000,
      "platform_fees_cents": 550,
      "total_amount_cents": 11550,
      "reference_type": "MONEY_MOVEMENT",
      "reference_id": "550e8400-e29b-41d4-a716-446655440010",
      "currency": "USD"
    },
    "received_at": 1736618000,
    "external_reference_id": "partner-bid-123",
    "asset_type": "TICKET",
    "external_ids": {...},
    "asset_details": {...},
    "config_details": {...},
    "item_details": {...}
  }
}

Transfer Type Values:

  • DIGITAL: Electronic tickets or digital items
  • PHYSICAL: Physical items requiring shipping (sealed TCG, sports cards)

Transfer Method Values:

  • EMAIL_TRANSFER: Email-based ticket transfer
  • MOBILE_TRANSFER: Mobile app transfer
  • ACCOUNT_TRANSFER: Direct account-to-account transfer
  • PLATFORM_TRANSFER: Via ticketing platform (Ticketmaster, AXS, etc.)
  • SHIPPING: Physical shipment with tracking (sealed TCG products)

Payment Details Fields:

  • winning_bid_amount_cents: Your winning bid amount
  • platform_fees_cents: TPX platform fees (typically 5%)
  • total_amount_cents: Bid amount + platform fees (processing fees added at settlement)
  • reference_type: Payment reference type (e.g., "MONEY_MOVEMENT")
  • reference_id: Payment reference ID for tracking (UUID)
  • currency: Currency code (ISO 4217, default "USD")

Additional Fields:

  • external_reference_id: Your tracking ID from the original bid (conditional or on-demand) - use this to reconcile the transfer with your bid tracking system
  • received_at: Unix timestamp when transfer was confirmed received

Important: This webhook signals that payment processing will occur. Your payment method (card, ACH, or wire) will be charged the total_amount_cents shown, plus payment processor fees (typically ~4.2%). The final total with processing fees is sent in the PAYMENT_SETTLED webhook. Use reference_id to track this payment in your accounting system.

9. PAYMENT_CHARGED​

Sent when partner payment is successfully initiated. For card payments, this means the charge was captured. For ACH or wire payments, this means the payment has been submitted and is processing.

{
  "msg_type": "PAYMENT_CHARGED",
  "msg_id": "990e8400-e29b-41d4-a716-446655440004",
  "sent_at": 1736618600,
  "source_id": "tradepost_payment_service",
  "destination_id": "partner_acme",
  "payload": {
    "conversation_id": "conv_123",
    "reference_type": "INSTANT_CASH_OFFER",
    "reference_id": "ico_456",
    "payment_details": {
      "winning_bid_amount_cents": 11000,
      "platform_fees_cents": 550,
      "total_amount_cents": 11550,
      "payment_method": "CARD",
      "reference_type": "MONEY_MOVEMENT",
      "reference_id": "550e8400-e29b-41d4-a716-446655440010",
      "transaction_id": "ch_3Abc123XYZ456",
      "payment_method_last4": "4242",
      "currency": "USD"
    },
    "charged_at": 1736618600,
    "external_reference_id": "partner-bid-123",
    "asset_type": "TICKET",
    "external_ids": {...},
    "asset_details": {...},
    "config_details": {...},
    "item_details": {...}
  }
}

Payment Details Fields:

  • winning_bid_amount_cents: Your winning bid amount
  • platform_fees_cents: TPX platform fees (typically 5%)
  • total_amount_cents: Bid amount + platform fees (processing fees added at settlement)
  • payment_method: Payment method used — CARD, ACH, or WIRE
  • reference_type: Payment reference type ("MONEY_MOVEMENT")
  • reference_id: Payment reference ID for tracking (UUID)
  • transaction_id: Payment processor transaction ID for reconciliation
  • payment_method_last4: Last 4 digits of the payment method charged
  • currency: Currency code (ISO 4217, default "USD")

Important: This confirms your payment was successfully initiated. Note: The total_amount_cents shown does not include payment processor fees — the final total with all fees is sent in the PAYMENT_SETTLED webhook. For ACH and wire payments, funds are in transit and settlement is confirmed via a separate PAYMENT_SETTLED webhook.

10. PAYMENT_FAILED​

Sent when partner payment fails. This can occur at charge time (card declined, ACH denied) or post-charge (ACH returned by bank).

{
  "msg_type": "PAYMENT_FAILED",
  "msg_id": "aa0e8400-e29b-41d4-a716-446655440005",
  "sent_at": 1736618900,
  "source_id": "tradepost_payment_service",
  "destination_id": "partner_acme",
  "payload": {
    "conversation_id": "conv_123",
    "reference_type": "INSTANT_CASH_OFFER",
    "reference_id": "ico_456",
    "payment_details": {
      "winning_bid_amount_cents": 11000,
      "platform_fees_cents": 550,
      "total_amount_cents": 11550,
      "payment_method": "CARD",
      "reference_type": "MONEY_MOVEMENT",
      "reference_id": "550e8400-e29b-41d4-a716-446655440010",
      "currency": "USD"
    },
    "failure_reason": "Your card was declined",
    "failure_code": "card_declined",
    "failed_at": 1736618900,
    "retry_allowed": true,
    "external_reference_id": "partner-bid-123",
    "asset_type": "TICKET",
    "external_ids": {...},
    "asset_details": {...},
    "config_details": {...},
    "item_details": {...}
  }
}

Failure Response Fields:

  • failure_reason: Human-readable explanation of payment failure
  • failure_code: Machine-readable error code from payment processor
  • failed_at: When the payment attempt failed (Unix timestamp)
  • retry_allowed: Whether Tradepost will retry the payment automatically
  • payment_method: Payment method that failed — CARD, ACH, or WIRE (may be null if undetermined)

Common Failure Codes:

  • card_declined: Card payment was declined by issuer
  • insufficient_funds: Card has insufficient funds
  • card_expired: Card has expired
  • card_invalid: Card number or details are invalid
  • processing_error: Payment processor error
  • PAYMENT_DECLINED: ACH payment was returned or denied by the bank

Action Required: If retry_allowed is true, ensure your payment method is valid and has sufficient funds for the retry. If false, contact support@tradepost.co immediately to resolve the payment issue and avoid account suspension.

11. PAYMENT_SETTLED​

Sent when partner payment is successfully settled and funds are transferred to the seller. This webhook includes the final fee breakdown with payment processor fees. For ACH and wire payments, this confirms the bank transfer completed successfully.

{
  "msg_type": "PAYMENT_SETTLED",
  "msg_id": "635d3221-dd9c-4c11-b52a-f570bd8c96f5",
  "sent_at": 1762498794,
  "source_id": "tradepost_auction_service",
  "destination_id": "partner_acme",
  "payload": {
    "conversation_id": "conv_123",
    "reference_type": "INSTANT_CASH_OFFER",
    "reference_id": "ico_456",
    "payment_details": {
      "winning_bid_amount_cents": 6000,
      "platform_fees_cents": 480,
      "total_amount_cents": 6752,
      "processing_fee_cents": 272,
      "payment_method": "CARD",
      "reference_type": "MONEY_MOVEMENT",
      "reference_id": "376e2a36-e091-45e3-9228-1b8b34d741ba",
      "currency": "USD"
    },
    "settled_at": 1762498794,
    "external_reference_id": "partner-bid-123",
    "asset_type": "TICKET",
    "external_ids": {...},
    "asset_details": {...},
    "config_details": {...},
    "item_details": {...}
  }
}

Payment Details Fields:

  • winning_bid_amount_cents: Your winning bid amount (6000 = $60.00)
  • platform_fees_cents: TPX platform fees, typically 5% of bid (480 = $4.80)
  • processing_fee_cents: Payment processor fees, typically ~4.2% of total (272 = $2.72)
  • total_amount_cents: Final total charged = bid + platform fees + processing fees (6752 = $67.52)
  • payment_method: Payment method used — CARD, ACH, or WIRE
  • reference_type: Payment reference type ("MONEY_MOVEMENT")
  • reference_id: Payment reference ID for tracking (UUID)
  • currency: Currency code (ISO 4217, default "USD")
  • settled_at: When the payment settlement completed (Unix timestamp)

Important: This is the authoritative final fee breakdown. Use this webhook for accurate accounting — the total_amount_cents here is the actual amount charged. Previous webhooks (PAYMENT_CHARGED) do not include processor fees.

Webhook Requirements​

Endpoint Configuration​

Your webhook endpoint must:

  • Use HTTPS with valid SSL certificate
  • Accept POST requests with JSON body
  • Return appropriate HTTP status codes
  • Respond within 5 seconds

Response Format​

Success Response​

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "received",
  "msg_id": "123e4567-e89b-12d3-a456-426614174000"
}

Error Response​

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Invalid message format",
  "msg_id": "123e4567-e89b-12d3-a456-426614174000"
}

Status Codes​

  • 200 OK: Message successfully received and processed
  • 400 Bad Request: Invalid message format or content
  • 401 Unauthorized: Authentication failure (future release)
  • 500 Internal Server Error: Partner system error

Message Handling​

Idempotency​

  • Messages may be retried on failure
  • Use msg_id to ensure idempotent processing
  • Store processed message IDs to prevent duplicate handling

Retry Policy​

Failed deliveries (non-200 responses or timeouts) will be retried:

  • Maximum 3 retry attempts
  • Exponential backoff between retries
  • Final failure after all retries exhausted

Message Ordering​

  • Messages within a conversation_id are ordered
  • Different conversations may process in parallel
  • Use timestamps for absolute ordering if needed

Security Considerations​

Request Validation​

Always validate incoming webhooks:

  1. Verify the User-Agent header matches TradepostTPX/1.0
  2. Check the X-TPX-Message-ID header is present
  3. Validate JSON structure and required fields
  4. Verify message types are recognized

IP Allowlisting (Future)​

In a future release, webhook requests will originate from specific IP ranges that can be allowlisted.

Testing Webhooks​

Development Tools​

  • Use webhook testing services like ngrok for local development
  • Log all incoming messages for debugging
  • Implement comprehensive error handling

Test Message​

You can verify your webhook is working by requesting a test message from Tradepost support.

Slack Integration​

TPX supports optional Slack integration to forward webhook messages to your team's Slack channels. This enables real-time notifications for critical events like auction results, accepted offers, and transfer confirmations.

Configuration​

Configure Slack integration through your partner account settings:

{
  "slack_enabled": true,
  "slack_webhook_url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
  "slack_send_all_messages": false
}

Configuration Options​

  • slack_enabled: Enable/disable Slack notifications for your account
  • slack_webhook_url: Your Slack incoming webhook URL (see Slack documentation)
  • slack_send_all_messages:
    • false (default): Only send critical alerts (auction results, accepted offers, transfers)
    • true: Send all TPX webhook messages to Slack

Message Format​

Slack messages include key information formatted for readability:

Auction Result Example:

Auction Result - WON
Asset: Taylor Swift | The Eras Tour (TICKET)
Your Bid: $110.00
Status: You won this auction!
Conversation: conv_123

Instant Cash Offer Accepted Example:

Instant Cash Offer Accepted
Asset: Prismatic Evolutions Elite Trainer Box (SEALED_TCG)
Status: Seller accepted your offer
Conversation: conv_456

Best Practices​

  1. Use a dedicated channel for TPX notifications to avoid noise
  2. Start with alerts only (slack_send_all_messages: false) then expand if needed
  3. Configure webhook URL securely - treat it like an API key
  4. Test integration by requesting a test message from Tradepost support

Setup Instructions​

  1. Create a Slack app in your workspace
  2. Enable incoming webhooks and copy the webhook URL
  3. Contact support@tradepost.co to configure Slack integration on your account
  4. Test with a sample webhook message

Next Steps​

  1. Implement webhook endpoint following these specifications
  2. Configure endpoint URL with your Technical Account Manager
  3. Review Asset Types to understand message data formats
  4. Implement GraphQL Responses to respond to messages
  5. Consider Conditional Bidding for automation
  6. Contact support@tradepost.co to test webhook connectivity

Support​

For webhook integration assistance:

← Bidding | Asset Types →

© 2026 Tradepost Markets Inc. All rights reserved.

Last updated on by Parker Stevenson