01
Verify the raw body
Calculate HMAC over the exact request body bytes before your JSON parser changes formatting or key order.
Webhook tester
Generate a signed BoltUtil webhook test payload
Create a realistic webhook body, calculate the HMAC-SHA256 signature, and copy a ready-to-run cURL command for your local or staging endpoint.
Checks
Raw body signing
Checks
HMAC-SHA256
Checks
Ready cURL
Signature workspace
Uses: HMAC_SHA256(timestamp + "." + rawBody, secret)
Signature
9bf05e5f9ec8375df95f7bf0e718c7e87277950e4fe57f63d4fb15d37c61ed10
Body status
Valid JSON body
Generated request
Send this request to your webhook endpoint. Your server should verify the signature against the raw request body and return HTTP 2xx only after safely recording the event.
curl -X POST "https://merchant.example.com/webhooks/boltutil" \
-H "Content-Type: application/json" \
-H "X-Bolt-Webhook-Timestamp: 1784819239648" \
-H "X-Bolt-Webhook-Signature: 9bf05e5f9ec8375df95f7bf0e718c7e87277950e4fe57f63d4fb15d37c61ed10" \
--data '{
"externalOrderId": "ORDER_2026_001",
"status": "CONFIRMED",
"amount": "199.000000",
"currency": "USDT",
"network": "TRC20",
"txHash": "0x1abd1849cf65896b103d3a252849f9460fc45d86cb1031c9c36c0205b0a2913c",
"confirmations": 20,
"destinationAddress": "TMerchantSettlementWallet",
"paidAt": "2026-05-25 12:30:00",
"confirmedAt": "2026-05-25 12:35:00",
"metadata": {
"plan": "pro",
"userId": "u_123"
}
}'02
Use timing-safe compare
Compare the received signature with a constant-time helper provided by your language runtime.
03
Return 2xx after durability
Only return success after recording the event or putting it into a durable internal queue.
Webhook troubleshooting
Why a payment webhook may fail
Most webhook problems come from signature verification, body parsing, retry handling, or returning success before your system has safely recorded the payment event.
Signature mismatch
The most common cause is signing parsed JSON instead of the exact raw body, or using a different timestamp than the request header.
Wrong secret
Use the webhook secret configured for the merchant endpoint. API keys and webhook secrets should be treated as different credentials.
Body parser changed the payload
JSON middleware can reorder or reformat payloads. Capture the raw body before parsing when verifying HMAC signatures.
Endpoint returns non-2xx
BoltUtil treats non-2xx responses as failed deliveries and will retry according to the configured retry policy.
Processing is not idempotent
Webhook retries can deliver the same event more than once. Store event IDs or transaction hashes to avoid duplicate fulfillment.
Success before durability
Return HTTP 2xx only after writing the event to your database or queue. Otherwise a crash can lose a completed payment notification.
FAQ
Webhook debugging questions
Use these checks when a payment is completed but your application does not update as expected.
Why does my webhook signature verification fail?
Verify the exact raw request body, the timestamp header, and the configured webhook secret. Signing parsed JSON or a reformatted body usually produces a different HMAC.
Should my webhook endpoint return SUCCESS in the response body?
A normal HTTP 2xx response is the important delivery success signal. The endpoint may return a simple JSON body, but the status code is what delivery systems should rely on.
How should I handle duplicate webhook deliveries?
Make the handler idempotent. Store a unique event ID, order ID plus status, or transaction hash before fulfilling the order, then ignore duplicates safely.
When should my endpoint return HTTP 2xx?
Return 2xx only after the payment event is safely recorded or queued. If validation fails or your system cannot persist the event, return a non-2xx status so it can be retried.