01
Verify the raw body
Calculate HMAC over the exact request body bytes before your JSON parser changes formatting or key order.
Probador de Webhooks
Genera un payload Webhook de BoltUtil firmado
Crea un body Webhook realista, calcula la firma HMAC-SHA256 y copia un comando cURL listo para tu endpoint local o de staging.
Comprobaciones
Firma de body crudo
Comprobaciones
HMAC-SHA256
Comprobaciones
cURL listo
Área de firma
Uses: HMAC_SHA256(timestamp + "." + rawBody, secret)
Firma
c122fe2855789460c45066b553ebf63d36f5d851813e8b16c248fba7b75d8250
Estado del body
Body JSON válido
Solicitud generada
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: 1784823588554" \
-H "X-Bolt-Webhook-Signature: c122fe2855789460c45066b553ebf63d36f5d851813e8b16c248fba7b75d8250" \
--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 qué puede fallar un Webhook de pago
La mayoría de problemas vienen de verificación de firma, parseo del body, gestión de reintentos o devolver éxito antes de registrar el evento de pago.
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.
Preguntas frecuentes
Preguntas de depuración Webhook
Usa estas comprobaciones cuando el pago está completado pero tu aplicación no se actualiza.
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.