> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tribridge.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Tribridge is a crypto payment gateway for Solana and Sui (TON is coming soon). API base URL is https://tribridge.onrender.com. Server-side calls authenticate with the x-api-key header using a tri_test_... key (fully simulated test mode, no real funds) or tri_live_... key (real mainnet payments) — never expose keys client-side. Merchant test mode is simulated, not testnet. Refunds are automatic only (underpaid/overpaid), there is no manual refund endpoint. Always verify webhook HMAC-SHA256 signatures from the X-Tribridge-Signature header before trusting payloads.

# Webhooks

> Real-time POST notifications for every payment state change, signed with HMAC-SHA256.

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](/refunds)). |
| `payment.overpaid` | Received more than expected (surplus refunded automatically). |

## Step 3 — Parse the payload

Every webhook delivers the same JSON shape:

```json Example payload theme={null}
{
  "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](/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`.

<Note>
  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.
</Note>

## Testing webhooks end to end

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.