Secure crypto IPN webhooks with HTTPS, signature checks, replay protection, and idempotency. Learn how to prevent retries from fulfilling orders twice.
A crypto IPN, or instant payment notification, is a callback message that reports the status of a cryptocurrency payment to your system. Handling one safely means four things: require HTTPS, verify the sender’s signature, check an authenticated timestamp against a replay window, and process each notification idempotently so a retry never charges or fulfills an order twice.
TL;DR:
- Low value digital goods can ship after the first notification, but wait for several blockchain confirmations before releasing valuable goods or funds.
- Verify the signature against the raw request body before parsing, and reject timestamps outside a tolerance of five minutes to block replayed deliveries.
- Store each event ID before processing, return 200 for authenticated duplicates, and queue work asynchronously so retries cannot fulfill orders twice.
- For payments across currencies or networks, validate both fields and retain original and converted amounts to reconcile settlements and prevent miscrediting.
- Run a periodic reconciliation job against the publisher’s API for orders still pending past the normal delivery window, and alert when on chain payments lack matching notifications.
A payment flow typically runs in three stages. A customer initiates a payment request through your checkout, pays on-chain or through a hosted page, and your system then receives an IPN reporting what happened. That notification is a message, not the payment itself, so the logic that decides what to do with it lives entirely on your side.
Merchants often confuse a notification with a confirmation. A notification tells you a transaction was seen or broadcast. A confirmation tells you how many blocks have been mined on top of it, which is the better signal of finality for higher-value orders. Low-value digital goods can often ship on first notification, while anything with real chargeback or fraud risk should wait for a small number of confirmations before you release goods or funds.
A typical IPN payload includes:
Automating against these fields matters because manual reconciliation does not scale. Once your system trusts a verified IPN, it can update order status, trigger fulfillment, and close the loop in your accounting without a human checking a block explorer for every sale.
Treat every IPN endpoint as a public attack surface, because it is one. The following controls, drawn from established webhook security guidance, form a baseline that applies whether you are receiving notifications from a payment gateway or any other webhook publisher.
Pro Tip: Verify the signature before you parse the JSON body. Parsing first and verifying second gives an attacker a window to exploit malformed input before your security check ever runs.
Signature verification alone is not a complete defense. Combine it with the authenticated timestamp and event-ID deduplication described below, since a stolen but valid signature replayed later is still a threat that the timestamp check is designed to stop.
Publishers resend IPNs when a delivery fails or times out, sometimes for days, so your endpoint will see the same event more than once. Building for that reality from day one avoids double-fulfilling orders or double-crediting accounts.
This pattern, accept fast, verify, deduplicate, then process off the request thread, keeps your endpoint responsive even during a burst of retries, and it is the same approach we recommend in our own guidance on building reliable webhook handlers.
Shipping an IPN integration safely comes down to a short sequence you can follow once and then repeat for every new webhook you add.
https:// URL, validate the host and IP against SSRF rules, and store the secret fingerprint securely.{timestamp}.{rawBody}, and comparing it with a constant-time function, a recipe documented in the OpenWOP webhook specification.A single verification check carries real weight: rejecting deliveries outside a five-minute timestamp window is the specific control that stops a captured, valid signature from being replayed hours or days later.
A typical integration looks like this: your checkout calls our API or hosted page to generate a payment request, the customer pays in one of over 110 supported cryptocurrencies, and once the network registers the transaction, an IPN lands on the callback URL you registered. Your endpoint verifies the signature, checks the timestamp, and then updates your order record, which is the same pattern described above applied to a live gateway rather than a generic spec.
For merchants running on common platforms, the practical shape of this is often a plugin or a short integration script rather than custom API code. Our walkthrough on accepting crypto payments on a community platform shows the registration, checkout, and notification steps end to end for one such setup, and the same sequence of request, payment, and callback applies regardless of which platform you run.
Marketplaces and platforms that need to split a payment across multiple parties, a seller and a commission account, for instance, can route the same IPN into logic that updates several ledgers from one notification rather than building separate payment flows for each party. White-label operators get the identical event structure, just delivered under their own branding, so the verification and idempotency code you write once covers every deployment mode.
When you accept more than one cryptocurrency, your IPN payload needs to carry enough context for you to reconcile each payment correctly regardless of which coin or network the customer chose. That means checking the currency field on every notification rather than assuming a single asset, and keying your internal records on the merchant reference rather than the coin type, since the same order might be paid in Bitcoin by one customer and a stablecoin by another.
Auto-conversion adds another wrinkle. When a payment is settled into a stablecoin or into fiat-equivalent value at the time of receipt, the IPN should report both the originally paid amount and currency and the converted settlement amount, so your accounting ties out without you having to pull a historical exchange rate separately. Build your processing logic to read both fields and store them, rather than discarding the original payment currency once conversion happens.
Network identification matters too. A token that exists on multiple chains needs a network field alongside the currency code, since crediting the wrong chain’s address format or mistaking one network’s token for another’s is a common source of reconciliation errors. Validate that combination against your supported list before you trigger any fulfillment action tied to the payment.
An IPN that never arrives is as operationally risky as one that arrives corrupted, because an order can sit unfulfilled while the customer assumes payment went through. Build alerting around three signals: delivery latency creeping above your normal baseline, a rising rate of signature failures, and a gap where an on-chain payment you can see through your dashboard has no matching notification in your logs.
When your endpoint returns an error, make sure it is the right kind of error. A 500 tells the publisher to retry, which is correct for a transient database outage. A 401 for a bad signature should not trigger endless retries from your side; instead, log it and alert, since a wave of signature failures often signals a misconfigured secret rather than an attack. Keep your retry and backoff behavior visible in your dashboards so a quiet failure doesn’t get lost in a queue nobody is watching.
For delayed deliveries specifically, build a reconciliation job that periodically checks payment status directly against the publisher’s API for any order still pending past a reasonable window. That job acts as a safety net under your IPN listener and catches the case where a notification was lost rather than merely late. Pair it with an alert that fires when the gap between “payment seen on-chain” and “IPN received” exceeds your normal delivery time, since that gap is usually the first sign something in the pipeline needs attention.
Most crypto payment gateways send a small, predictable set of event types rather than a sprawling list, which keeps your handler logic manageable. A payment created event fires when a checkout session or payment request is generated, carrying the merchant reference, requested amount, and currency, but no transaction hash yet since nothing has been paid. A payment pending event follows once a transaction is seen on the network but not yet confirmed, adding the transaction hash and a status field set to pending.
A payment confirmed event is the one most fulfillment logic waits for, carrying the final confirmed amount, the transaction hash, confirmation count, and often the converted settlement value if auto-conversion is enabled. A payment failed or expired event reports when a payment request times out or a transaction is dropped, which matters for releasing any reserved inventory tied to that order.
Each of these event types shares a common envelope, the event ID, timestamp, and merchant reference described earlier, with a type-specific payload nested inside. Writing your handler to switch on the event type field, rather than inferring status from which fields are present, keeps the logic readable and makes it easier to add a new event type later without breaking existing handling.
Signature verification and timestamp checks handle authenticity and freshness, but a few additional controls reduce your exposure further. IP whitelisting restricts incoming connections to the known address range a publisher sends from, so even a correctly signed request from an unexpected source gets an extra layer of scrutiny, useful as a defense-in-depth measure rather than a replacement for signature checking.
Rate limiting your own endpoint protects against both abuse and accidental floods, a misbehaving retry loop on the publisher’s side should not be able to overwhelm your processing queue. Pair that with strict content-type checking, rejecting anything that isn’t the expected JSON format before you attempt to parse it, which closes off a class of injection attempts that rely on unexpected payload formats.
Finally, isolate your webhook processing from your core application logic where you can. Running IPN ingestion in a separate service or worker process means a vulnerability or crash in that pathway doesn’t take down checkout or account management, and it makes it easier to apply the stricter network and logging rules webhook endpoints need without affecting the rest of your stack.
The most common mistake we see is merchants trusting the payload before verifying it, usually because the happy path works fine in testing and the signature check gets added later, if at all. The second is a timestamp tolerance set too tight for merchants with poorly synced server clocks, which causes legitimate notifications to fail for reasons that have nothing to do with security.
Our rollout recommendation is simple: start with a staged integration against a test harness, watch your logs closely for the first real transactions, and treat observability as part of the build, not an afterthought bolted on after an incident.
— Dustin
Building signature verification, secret rotation, and idempotent processing from scratch takes real engineering time away from your actual product. Our gateway handles that groundwork for you: hosted checkout, API, and webhook integrations covering 110+ cryptocurrencies, each with documented verification recipes so your team writes the handler once and trusts it.
Every webhook gets its own secret, rotation is documented step by step, and delivery logging is built in from the start, so the controls covered in this guide come configured rather than homemade. Review the integration paths on our gateway page and connect your first endpoint today.
An IPN is a notification message telling you a payment event occurred, while a confirmation is a count of blocks mined on top of that transaction. Many merchants act on the IPN immediately for low-risk orders but wait for several confirmations before releasing high-value goods or funds.
A common and well-supported tolerance is plus or minus five minutes, which blocks replay attacks while allowing for normal clock drift between servers. Tightening it further risks rejecting legitimate notifications from merchants whose server clocks are not precisely synced.
Parsing a JSON payload and then re-serializing it can change whitespace or key order, which invalidates a signature computed over the original bytes. Verification libraries and specs like OpenWOP require checking the signature against the raw body before any parsing happens.
IPN delivery is part of standard transaction processing rather than a separate charge. CryptoPayr’s transaction fees range from Standard at 2% to Enterprise at 0.1% per month depending on volume tier, or a flat $0.10 per payment option, with no separate webhook fee.
Run a periodic reconciliation job that checks payment status directly against the publisher’s API for orders still pending past your normal delivery window. This catches lost notifications and prevents an order from sitting unfulfilled simply because a callback failed to arrive.
Open a free CryptoPayr account and take your first crypto payment the same day.
Get started for free
Add wallet support to crypto checkout with hosted checkout, plugins, or an API fallback. Cover mobile handoffs, secure requests, and gasless options.
Cut crypto checkout fees and reduce abandonment with five changes you can ship in a sprint, from fee visibility to gas sponsorship and payout routing.
Merchant playbook to hedge crypto payments and keep treasury liquid: auto convert, staged stablecoins, routing, FX hedges, and no KYC onboarding.