Webhooks overview

HelaMesh sends a signed HTTP POST to your webhook URL when on-chain activity that concerns your client is confirmed. Your backend should:

1. Verify the signature
2. Handle the event by type (event field)
3. Return 200 OK within 10 seconds

If you return any non-2xx status (or time out), HelaMesh retries with exponential backoff.

Event types

Event	When it fires	Who uses it
payment.confirmed	An invoice-based payment reaches required confirmations	Standard invoice flow
transfer.confirmed	A USDT deposit arrives at a derived sub-wallet address	Platforms using HD sub-wallet derivation

Invoice flow (payment.confirmed)

Chain confirms payment
       │
       ▼
HelaMesh poller detects → marks invoice CONFIRMED
       │
       ▼
Webhook enqueued → dispatcher claims → POST to your URL
       │              ↑                      │
       │              └──── retry ───────────┤
       │                   (on non-2xx)      │
       ▼                                     ▼
Invoice stays CONFIRMED          Your backend verifies
 until 2xx received                signature + updates DB
       │                                     │
       └──── 2xx received ──→ COMPLETED ◄────┘

Key principle: CONFIRMED → COMPLETED is gated on successful webhook delivery. An invoice stays CONFIRMED until your backend ack's the webhook.

Derived-address flow (transfer.confirmed)

User sends USDT to their derived address
       │
       ▼
HelaMesh poller detects transfer → checks confirmation depth
       │
       ▼  (≥ required confirmations)
Webhook enqueued → dispatcher claims → POST to your URL
                                              │
                                              ▼
                                   Your backend looks up user
                                   by hdIndex, credits balance

No invoice is created in this flow. Use the hdIndex in the payload to identify which of your users received the funds.

Read next: Webhook payload, Verifying signatures, Retries.