Webhooks

Tribridge sends a POST to your registered endpoint whenever a payment’s status changes. Use these — not the customer’s redirect — as the source of truth for your order status.

Step 1 — Register an endpoint

Register via POST /webhooks from an authenticated dashboard session. Register separate endpoints for test and live mode — each gets its own signing secret, returned only once at creation. Your endpoint must be publicly reachable over HTTPS and respond quickly (see Step 4).

Step 2 — Know the event types

Event	When it fires
`payment.confirmed`	The on-chain transaction reached finality.
`payment.swept`	Funds were forwarded from the deposit address to the settlement vault (gas paid by Tribridge).
`payment.completed`	The payment is fully settled. Fulfill the order.
`payment.expired`	The payment window elapsed before funds arrived.
`payment.underpaid`	Received less than expected (see Refunds).
`payment.overpaid`	Received more than expected (surplus refunded automatically).

Step 3 — Parse the payload

Every webhook delivers the same JSON shape:

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"
}

Before trusting any of it, verify the signature headers (full walkthrough in Authentication):

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

Recompute HMAC-SHA256 over the raw body with your endpoint’s secret and compare in constant time.

Step 4 — Acknowledge correctly

Respond with a 2xx status within a few seconds to acknowledge delivery.
Tribridge retries failed deliveries with exponential backoff, up to 5 attempts. A non-2xx response (including a signature mismatch) triggers a retry — so only return 2xx after you have durably recorded the event.
Make your handler idempotent: the same event may be delivered more than once. Key off payment_id + event.

Your endpoint’s signing secret is returned once when you create the webhook — keep it safe and never commit it. Test and live endpoints have different secrets.

Testing webhooks end to end

Register a test endpoint pointing at your server (use a tunnel like ngrok for localhost).
Create a payment with your tri_test_... key and open the checkout_url.
Click Simulate Payment — your test endpoint receives the full event sequence with is_test: true.
Confirm your signature check passes and your order updates, then repeat with live credentials.

Payments

Developers

Step 1 — Register an endpoint

Step 2 — Know the event types

Step 3 — Parse the payload

Step 4 — Acknowledge correctly

Testing webhooks end to end

​Step 1 — Register an endpoint

​Step 2 — Know the event types

​Step 3 — Parse the payload

​Step 4 — Acknowledge correctly

​Testing webhooks end to end

Step 1 — Register an endpoint

Step 2 — Know the event types

Step 3 — Parse the payload

Step 4 — Acknowledge correctly

Testing webhooks end to end