Webhooks overview

When a payment hits CONFIRMED, HelaMesh sends a signed HTTP POST to the webhook URL on your client. Your backend should:

1. Verify the signature
2. Look up the invoice by ID in your own database
3. Mark the order as paid
4. Return 200 OK within 10 seconds

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

The big picture

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. This ensures your backend and HelaMesh agree on the payment status.

Read next: Webhook payload, Verifying signatures, Retries.