Webhooks & events

Merchant webhooks — TBBN → you

Register a webhook endpoint and TBBN calls it as trades and listings progress:

listing.created, listing.updated, offer.created, offer.accepted, offer.rejected, trade.created, trade.accepted, trade.completed, trade.cancelled, trade.counterparty_hold_started, trade.closed_unreciprocated, checkout.started, checkout.completed, checkout.failed, reservation.created, reservation.expired, fulfillment.started, fulfillment.completed, seller.linked.

reservation.created/.expired/.failed are the ones to subscribe to if you want to lock your own inventory in real time as items get reserved for a trade — see the integration walkthrough's section on this.

Business webhooks (Space) — TBBN → you

Space booking lifecycle events, using the same signing/retry mechanics as the merchant webhooks above. Subscribe per-Business via your dashboard's Webhooks section or POST /v1/webhooks/business-subscriptions:

space_booking.created, space_booking.consent_required, space_booking.consented, space_booking.paid, space_booking.cancelled, space_booking.no_show, space_booking.approval_requested, space_booking.approved, space_booking.completed.

space_booking.approval_requested fires when a booking that requires host approval is created with no payment taken yet; space_booking.approved fires once the host clears it. A host decline publishes the existing space_booking.cancelled with a reason describing it, rather than a separate event type.

Webhooks you send — you → TBBN

Your own checkout and fulfillment endpoints report back to TBBN:

payment.completed, payment.failed, item.reserved, item.unreserved, item.sold, item.unavailable, fulfillment.started, fulfillment.completed, returned, cancelled.

Payload shape

{
  "event": "checkout.started",
  "tradeSessionId": "ts_01hxyz...",
  "side": "A",
  "originalPrice": 500,
  "tradeAmount": 50,
  "currency": "USD",
  "timestamp": "2026-07-01T12:00:00Z"
}

Signature scheme

Every outbound webhook includes X-TBBN-Signature: t=<unix_ts>,v1=<hmac_sha256_hex> computed over ${timestamp}.${rawBody} using the signing secret issued alongside your API key. Reject any request older than a 5-minute replay window. Full verification code ships in every SDK (verifyWebhookSignature()).

Delivery guarantees

At-least-once delivery, exponential backoff retry (5 attempts over ~24h), dead-letter queue with manual replay available from your dashboard and via POST /v1/webhooks/deliveries/:id/replay. Replays aren't automatically deduplicated on your end — build your handler to be idempotent, keyed by tradeSessionId + event, same as API conventions's idempotency-key requirement on the calls you make to TBBN.