Webhook tester

Debug webhook callbacksGet the signature right

Edit a sample payload and generate an HMAC-SHA256 signature and cURL request. Check your callback verification in a test environment.

Webhook signature workspace

Configure the test, edit the payload, and copy the signature and request.

01

Configure the test

Set the endpoint, test secret, and timestamp.

Signatures are calculated in your browser. Use a test secret for debugging.

Unix timestamp in milliseconds, matching BoltUtil callback headers.

02

Edit the payload, generate a signature

The signature and cURL update as you edit the JSON.

Signature

HMAC-SHA256

Enter a test secret, valid timestamp, and JSON to generate a signature.

Calculated from the current timestamp, exact body, and test secret.

Valid JSON
cURL / POSTTest request
Enter a valid endpoint, secret, timestamp, and JSON to generate a request.

This simulated USDC order callback can also use USDT. Orders, addresses, and transaction hashes are examples, not evidence of payment.

This tool only generates requests. Run cURL manually in your test environment to send one.

Signature verification

Verify before you proceed

Verify using the same signing rule, safely record the event, then update your business order.

Read the verification guide
HMAC_SHA256(timestamp + "." + rawBody, secret)
  1. 01

    Verify the raw body

    Use the millisecond timestamp from the header and the exact raw body to calculate HMAC before parsing JSON. Whitespace, line breaks, and field order affect the signature.

  2. 02

    Use timing-safe compare

    Compare the received signature with a constant-time helper provided by your language runtime.

  3. 03

    Record safely, then return 2xx

    Only return success after recording the event or putting it into a durable internal queue.

Webhook troubleshooting

Not matching? Start here

Check the original body, secret, and response status to locate the issue.

01

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.

02

Wrong secret

Use the webhook secret configured for the merchant endpoint. API keys and webhook secrets should be treated as different credentials.

03

Body parser changed the payload

JSON middleware can reorder or reformat payloads. Capture the raw body before parsing when verifying HMAC signatures.

04

Endpoint returns non-2xx

Non-2xx responses count as failed deliveries. Further attempts depend on the callback type, response status, and retry policy.

05

Processing is not idempotent

A notification may be delivered more than once. Deduplicate using the actual order identifier and status, or a unique event ID, before fulfillment.

06

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

Questions while debugging

Signature verification, responses, and duplicate deliveries.

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?

No. BoltUtil uses the HTTP status code: 2xx means successful delivery. The body does not need to contain SUCCESS. Verify the signature and safely record the event first.

How should I handle duplicate webhook deliveries?

Deduplicate with a database constraint or atomic operation. Traditional order callbacks can use the order identifier and status; callbacks with a unique event ID can use that ID. A transaction hash alone can cover multiple transfers.

When should my endpoint return HTTP 2xx?

Return 2xx after verifying the signature and safely recording the event in a database or durable queue. Use an appropriate error status if verification or persistence fails. Retries depend on callback type and policy.