Webhooks overview

HelaMesh sends a signed HTTP POST to your webhook URL when a payment confirms — regardless of which rail was used. 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_link.confirmed	A payment link is paid via any rail (M-Pesa, TRON, BSC)	Everyone using payment links
transfer.confirmed	A USDT deposit arrives at a derived sub-wallet address	Platforms using HD sub-wallet derivation

Payment link flow (payment_link.confirmed)

Customer pays (M-Pesa PIN / on-chain tx)
       │
       ▼
HelaMesh confirms payment → marks link CONFIRMED
       │
       ▼
Webhook enqueued → dispatcher → POST to your URL
       │              ↑               │
       │              └─── retry ─────┤  (on non-2xx)
       ▼                              ▼
Link stays CONFIRMED       Your backend verifies
 until 2xx received         signature + fulfils order

One webhook event covers all rails — check confirmedRail in the payload to see how the customer paid.

Derived-address flow (transfer.confirmed)

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

No payment link is involved in this flow. Use hdIndex in the payload to identify which of your users received the funds.

Read next: Webhook payload, Verifying signatures, Retries.