01
Verify the raw body
Calculate HMAC over the exact request body bytes before your JSON parser changes formatting or key order.
Kiem tra Webhook
Tao payload Webhook BoltUtil da ky
Tao body Webhook thuc te, tinh chu ky HMAC-SHA256 va sao chep lenh cURL san sang cho endpoint local hoac staging.
Kiểm tra
Ky body goc
Kiểm tra
HMAC-SHA256
Kiểm tra
cURL san sang
Khu vuc tao chu ky
Uses: HMAC_SHA256(timestamp + "." + rawBody, secret)
Chu ky
cdc79f8e36d3024d4d2e9c963c7a835bf358f312ad656150abf35d8cbbbbf010
Trang thai body
Body JSON hop le
Yeu cau da tao
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: 1784823594419" \
-H "X-Bolt-Webhook-Signature: cdc79f8e36d3024d4d2e9c963c7a835bf358f312ad656150abf35d8cbbbbf010" \
--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.
Xu ly su co Webhook
Vi sao Webhook thanh toan co the that bai
Phan lon van de den tu xac minh chu ky, parse body, xu ly retry hoac tra ve thanh cong truoc khi ghi ben vung su kien thanh toan.
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.
Câu hỏi thường gặp
Cau hoi debug Webhook
Dung cac kiem tra nay khi thanh toan da hoan tat nhung ung dung cua ban chua cap nhat.
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.