01
Verify the raw body
Calculate HMAC over the exact request body bytes before your JSON parser changes formatting or key order.
Testador de Webhooks
Gere um payload Webhook assinado da BoltUtil
Crie um body Webhook realista, calcule a assinatura HMAC-SHA256 e copie um comando cURL pronto para seu endpoint local ou de staging.
Verificações
Assinatura do body bruto
Verificações
HMAC-SHA256
Verificações
cURL pronto
Área de assinatura
Uses: HMAC_SHA256(timestamp + "." + rawBody, secret)
Assinatura
a4b7334574b95b4bc7b965632d8867bc5a98f059e4fac223059752fb49c58b16
Status do body
Body JSON válido
Requisição gerada
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: 1784823588335" \
-H "X-Bolt-Webhook-Signature: a4b7334574b95b4bc7b965632d8867bc5a98f059e4fac223059752fb49c58b16" \
--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.
Diagnóstico de Webhooks
Por que um Webhook de pagamento pode falhar
A maioria dos problemas vem de verificação de assinatura, parsing do body, tratamento de retentativas ou retorno de sucesso antes de registrar o evento.
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.
Perguntas frequentes
Perguntas de depuração Webhook
Use estas verificações quando o pagamento foi concluído mas sua aplicação não atualizou.
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.