Webhooks

AuthProxy can send outbound HTTP notifications (webhooks) to registered applications when events occur in the platform — such as transactions, chat messages, or security events.

How It Works

ItBuild Module (TrexWallet, Chat, etc.)
    │
    │  Event occurs (transaction, message, etc.)
    ▼
AuthProxy EventHub
    │
    ├─── SSE Connection → Real-time to browser
    │
    └─── Webhook Service → HTTP POST to registered app URL

1. Backend modules generate events (transactions, messages, etc.)
2. AuthProxy collects events through polling or direct push
3. For each registered application with a webhook_url, AuthProxy sends an HTTP POST with the event data
4. Delivery status is tracked per application (success/failure counters)

Application Registration

Applications are registered via the user_app table or admin panel:

Implementation detail

Source-level examples and database statements are maintained in the module repositories. This public page describes the operational contract and configuration intent.

Register via API

curl -X POST http://authproxy/auth/v1/app/upsert_usr_app \
  -H "Content-Type: application/json" \
  -H "Cookie: sid=your_session" \
  -d '{
    "name": "My Backend Service",
    "url": "https://myapp.com",
    "webhookUrl": "https://myapp.com/api/webhooks/itbuild",
    "currencies": ["BTC", "USDT", "EUR"],
    "netTypes": [200, 201]
  }'

The body matches the UserAppIn DTO from ItBuild.Shared.AuthProxy. currencies is a list of currency codes (max 20) and netTypes is a list of ContractTypeEnum byte values (max 30) — both arrays, not space-separated strings. A null field means "don't change" for an existing app. There is no tariffGroup field. Property names are serialised as written in C# (camelCase) — there is no automatic snake_case conversion (JSON Property Naming).

Configure via Admin Panel

Navigate to /ProxyAdmin/UserApps to manage application registrations and webhook URLs.

Event Format

Webhooks deliver events as HTTP POST requests with JSON body matching BroadcastEvent (ItBuild.Shared.Events):

POST /api/webhooks/itbuild HTTP/1.1
Content-Type: application/json
X-API-Key: app_api_key

{
  "module": "wallet",
  "tick": "1707220800000000000",
  "type": "TxInWallet",
  "data": {
    "id": "1707220800000000123",
    "tick": "1707220800000000123",
    "currency": "USDT",
    "txType": 2,
    "state": 7,
    "amount": 10.00,
    "fee": 0.0,
    "externalId": "0",
    "appId": "0",
    "partnerInfo": null,
    "tag": null,
    "dateTime": "2026-02-06T12:00:00Z"
  }
}

For wallet events data is a TxEventOut: id, tick, currency, txType (TransactTypeEnum), state (TransactStateEnum), amount/fee (decimal numbers, already scaled by currency precision), externalId, appId, partnerInfo, tag, dateTime. int64 ids (id, tick, externalId, appId) carry [LongToString] and arrive as strings. Enum fields (txType, state) serialise as their numeric value by default (no JsonStringEnumConverter is registered). crmId and subject are routing-only and are not sent on the wire. The shape of data depends on the source event: TxEventOut for wallet events, ChatEventOut for chat events, etc. See ItBuild.Shared.Events for the typed payloads.

Event Types

The platform-defined types currently emitted to webhooks include (non-exhaustive):

Event Type	Module	Description
TxInWallet	TrexWallet	Incoming deposit/transfer to wallet
SwapChanged	TrexWallet	Swap state change
ExchangeChanged	TrexWallet	Exchange transaction state change
OrderChanged	TrexWallet	Order state change
TransferCompleted	TrexWallet	Internal/external transfer finished
NewChatMessage	Chat	New message in chat

The authoritative list lives in module code (PushDispatcher, EventPoller, and module-specific event emitters). Customer Core modules can publish their own types under module: "core".

Delivery Behavior

• Retry: Failed deliveries are retried on the next event poll cycle
• Tracking: success_count and failed_count are updated per delivery
• Cursor: last_tick tracks the last successfully delivered event, ensuring no events are missed
• Ordering: Events are delivered in chronological order (by timetick)
• Batching: Multiple events may be included in a single delivery

Filtering

Applications can filter which events they receive:

Filter	UserAppIn field	Example
Currencies	currencies	"BTC USDT EUR" — only events for these currencies
Network types	netTypes	"200 201 151" — only events for these networks
Tariff group	tariffGroup	0-63 — application group for fee routing

Monitoring

Check webhook health in the admin panel (/ProxyAdmin/UserApps):

• Success count — total successful deliveries
• Failed count — total failed deliveries
• Last tick — timestamp of last sent event

A high failed_count relative to success_count indicates connectivity issues with the webhook endpoint.

Security

• Webhook URLs must be HTTPS in production
• Each delivery includes the X-API-Key header for verification
• The receiving application should validate the API key before processing events
• Webhook endpoints should respond within a reasonable timeout (5 seconds)