Webhooks

Stay in sync with on-chain events and update your order status in real-time.

Event Types

TriBridge sends a POST to your registered endpoint whenever a payment's status changes. Register separate endpoints for test and live mode via POST /webhooks.

payment.confirmedThe on-chain transaction reached finality and the payment is complete.

payment.completedFunds have been forwarded/swept to your payout wallet.

payment.expiredThe payment window elapsed before funds arrived.

payment.underpaidReceived less than the expected amount.

payment.overpaidReceived more than the expected amount.

Payload Structure

Every webhook delivers the same JSON shape. Verify the X-Tribridge-Signature header (HMAC-SHA256 of the raw body using your endpoint's webhook secret) before trusting it.

Example payload

{
  "event": "payment.confirmed",
  "payment_id": "b3f1c2a0-1d4e-4f2a-9c8b-2e7a6f5d4c3b",
  "status": "completed",
  "amount": 99.00,
  "currency": "USD",
  "chain": "solana",
  "tx_hash": "6p2m...y81z",
  "received_amount_native": "0.6421",
  "expected_amount_native": "0.6421",
  "is_test": true,
  "timestamp": "2026-08-25T12:05:33.000Z"
}

Headers

Request headers

X-Tribridge-Signature: sha256=9f3a1c7e8b2d4f6a0c1e3b5d7f9a2c4e
X-Tribridge-Timestamp: 2026-08-25T12:05:33.000Z
Content-Type: application/json

Respond with a 2xx status within a few seconds to acknowledge delivery. TriBridge retries failed deliveries with exponential backoff (up to 5 attempts).

Your endpoint's signing secret is returned once when you create the webhook — keep it safe and never commit it.