Tetron.fun - Webhooks & Event Subscriptions

Configure and consume real‑time callbacks for score updates and on‑chain events.

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

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