Using invoice.paid Webhook Events in a Crypto Invoicing API (2026)
A developer guide to invoice.paid and payment.confirmed webhook events in a crypto invoicing API for 2026 — idempotency, verification, testnet testing, and reliable handling.
TL;DR
Webhook events like invoice.paid and payment.confirmed let your system react the moment a crypto invoice is settled — provision access, update a record, trigger fulfillment. To use them reliably, handle them idempotently (safe to receive twice), verify their authenticity, and test against testnet before mainnet. Here's the developer-focused walkthrough.
I run product at Settlematic, so this reflects how we think about webhooks; the principles are general API hygiene.
What the events are for
A crypto payment confirming on-chain is an event your application often needs to act on. Rather than polling for status, you subscribe to webhooks and the platform calls your endpoint when something happens:
- invoice.paid — the invoice's balance is fully settled.
- payment.confirmed — a payment (which may be partial) has confirmed on-chain.
With these, you can grant access, mark an order fulfilled, write to your data warehouse, or notify a team — driven by the actual settlement rather than a guess. (API & webhooks.)
Idempotency is non-negotiable
Webhook delivery is "at least once" by nature — networks retry, and you may receive the same event more than once. If your handler isn't idempotent, a retry could double-provision, double-count revenue, or double-send an email. The fix is standard: treat each event's ID as a dedupe key, record processed IDs, and make the handler a no-op if it sees an ID it already handled. Design every consumer so that receiving the same invoice.paid twice produces the same end state as receiving it once.
Verify authenticity
Your endpoint is public, so verify that an incoming call genuinely came from the platform before acting on it — typically by checking a signature or shared secret per the API's documentation. Never provision off an unverified payload; an attacker who knows your endpoint shouldn't be able to fake a invoice.paid. Combine verification with idempotency and your handler is both safe and robust.
Handle partial payments correctly
Because crypto invoices can be paid in tranches, distinguish payment.confirmed (a payment landed, balance may still be open) from invoice.paid (balance closed). Provision or fulfill on the event that matches your business rule — sometimes that's full payment, sometimes it's first payment. Don't assume one confirmed payment means the invoice is settled. See partial payments.
Test on testnet first
This is the step teams skip and regret. Wire your webhook consumer against a sandbox, send testnet invoices, pay them, and confirm your handler behaves under retries and partial payments before any real money flows. If a platform can't deliver testnet webhooks, your integration testing happens in production — exactly where you don't want surprises. Start a free workspace and exercise the events end to end.
The bottom line
invoice.paid and payment.confirmed webhooks make crypto settlement event-driven and reliable — if you build idempotent, verified handlers and test them on testnet. Get those three right and the integration is solid. The broader integration criteria are in best crypto invoicing for SaaS.
Explore Settlematic
Ready to try the workflow in your own workspace? Start on testnet, then explore our how it works guide and product features.