01
Verify the raw body
Calculate HMAC over the exact request body bytes before your JSON parser changes formatting or key order.
Webhook test araci
Imzali BoltUtil Webhook test payload'u olustur
Gercekci bir Webhook body olustur, HMAC-SHA256 imzasini hesapla ve local veya staging endpoint'in icin hazir cURL komutu kopyala.
Kontroller
Ham body imzasi
Kontroller
HMAC-SHA256
Kontroller
Hazir cURL
Imza alani
Uses: HMAC_SHA256(timestamp + "." + rawBody, secret)
Imza
16e1f8df25ed79813660e56b9ca3865216a23e4ce0bb1596e03fb8013f25e6e9
Body durumu
Gecerli JSON body
Olusturulan istek
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: 1784826872960" \
-H "X-Bolt-Webhook-Signature: 16e1f8df25ed79813660e56b9ca3865216a23e4ce0bb1596e03fb8013f25e6e9" \
--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 sorun giderme
Odeme Webhook'u neden basarisiz olabilir
Sorunlarin cogu imza dogrulama, body parse etme, retry yonetimi veya odeme olayini kalici kaydetmeden once basarili yanit donmekten kaynaklanir.
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.
SSS
Webhook debug sorulari
Odeme tamamlandigi halde uygulaman guncellenmediginde bu kontrolleri kullan.
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.