Separate payment success from callback success
A completed order means the payment layer worked. A retry means the merchant application did not accept or process the first callback cleanly.
Why a USDT payment webhook may only succeed on retry
When the blockchain payment is already completed but the merchant app updates only after a second webhook attempt, the issue is usually in endpoint availability, signature handling, timeout behavior, or non-idempotent fulfillment.
- Built for
- Webhook retries
- Built for
- Callback debugging
- Built for
- Idempotent fulfillment
Webhook retry diagnosis
Webhook retry diagnosis
1. Confirm the order status is already completed
2. Open the webhook delivery log for the order
3. Check first attempt HTTP status, timeout, and response body
4. Verify raw body signature before parsing JSON
5. Make fulfillment idempotent by order ID and tx hash
6. Fix the endpoint, then resend or wait for the next retryWebhook retry troubleshooting flow
Best for developers debugging completed USDT orders where the first callback fails but a later retry succeeds.
- 01
Confirm the order is completed in BoltUtil so you know the chain scanner already matched the payment.
- 02
Open webhook logs and compare the first attempt with the successful retry: status code, latency, timeout, and response body.
- 03
Verify your endpoint reads the raw request body for HMAC validation before any JSON parser changes the payload.
- 04
Make fulfillment idempotent by external order ID and tx hash, then resend the webhook after fixing the root cause.
Inspect response codes and latency
Timeouts, redirects, 4xx validation errors, 5xx crashes, and slow database writes are common reasons the first delivery is marked failed.
Design for safe retries
Webhook handlers should return fast, verify signatures correctly, and treat repeated notifications as normal instead of creating duplicate fulfillment.
Integration notes
What matters before production
The first attempt often exposes a cold path
Cold serverless functions, sleeping containers, DNS delays, or lazy database connections can make the first webhook exceed the timeout while the retry succeeds.
Signature validation must use the raw body
If middleware parses, formats, or reorders JSON before HMAC verification, the first callback may be rejected even though the payload is valid.
A retry is expected behavior, not a duplicate payment
Merchants should store processed order IDs and transaction hashes, then return a successful response for already-processed callbacks.
Questions merchants ask before going live
These answers help developers, founders, and support teams understand the payment lifecycle before accepting real USDT payments.
Does a retry mean the USDT payment was detected late? +
Not necessarily. If the order is already completed, the scanner matched the payment and the retry is about merchant callback delivery.
What response should my webhook endpoint return? +
Return a 2xx response after verifying the signature and durably recording the event. Avoid redirects and long blocking work.
How do I prevent duplicate fulfillment during retries? +
Store processed external order IDs and transaction hashes, and make repeated valid callbacks return success without granting value twice.
Related resources
Launch a cleaner USDT payment flow
Create orders, monitor transfers, and notify your backend without asking customers to send screenshots.
Create free account