> For the complete documentation index, see [llms.txt](https://tetron.gitbook.io/tetron/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tetron.gitbook.io/tetron/tetron.fun-webhooks-and-event-subscriptions.md).

# Tetron.fun - Webhooks & Event Subscriptions

## Webhooks & Event Subscriptions

TetronFun supports real‑time event delivery via webhooks and message subscriptions. This page describes how to configure endpoints, subscribe to channels, secure your callbacks, and handle retries.

### 1. Webhook Overview

* **Purpose**: Receive push notifications when a scoring result is available or when on‑chain events of interest occur.
* **Supported Events**:
  * `score.completed` – a transaction scoring has finished
  * `address.updated` – reputation score change for a wallet
  * `routing.executed` – smart route execution details

### 2. Configuring Webhooks

1. **Create a Webhook Endpoint**\
   In the dashboard, navigate to **Settings → Webhooks** and click **Add Endpoint**.
2. **Specify URL & Events**
   * Enter a secure HTTPS URL (TLS 1.2+).
   * Select events to subscribe.
3. **Secret Signing Key**\
   Dashboard generates a `secret` used to HMAC‑SHA256 sign each payload.

### 3. Payload Format

```json
POST /webhook HTTP/1.1
Host: yourapp.com
Content-Type: application/json
X-TetronFun-Signature: <HMAC_SHA256_HEX>
X-TetronFun-Event: score.completed
X-TetronFun-Timestamp: 2025-05-17T12:34:56Z

{
  "event": "score.completed",
  "data": {
    "transaction_id": "tx_01F8XYZ...",
    "fraud_score": 12.7,
    "reputation_score": 87.3,
    "recommendation": "approve"
  }
}
X-TetronFun-Signature: HMAC_SHA256(secret, timestamp + '.' + body)
X-TetronFun-Timestamp: ISO 8601 timestamp used in signature
4. Handling & Validation

Validate Timestamp (±5 minutes)
Compute HMAC and compare to X-TetronFun-Signature
Acknowledge Quickly with HTTP 2xx
Idempotency: Use transaction_id to detect duplicates
5. Retry Policy

TetronFun retries up to 5 times, with exponential backoff (1m, 2m, 4m, 8m, 16m)
Final failure triggers alert in dashboard
6. WebSocket Subscriptions

URL: wss://api.tetronfun.com/v1/events
Authenticate:
{ "action": "authenticate", "apiKey": "<YOUR_API_KEY>" }
Subscribe:
{ "action": "subscribe", "channels": ["score.completed", "address.updated"] }
Receive: JSON messages identical to webhook payloads
```