Notifications

HashNut sends webhook notifications to your server when an order's state changes. This page covers the notification payload, signature verification, and retry policy.

Webhook Delivery

When an order state changes (e.g., from INIT to PAID, or from CONFIRMING to SUCCESS), HashNut sends an HTTP POST request to the Notify URL configured for that order.

Notification Payload

The notification body is intentionally minimal. It contains only the identifiers needed to query the full order details:

{
  "payOrderId": "PO202606210001",
  "merchantOrderId": "ORDER-20260621-001",
  "accessSign": "BASE64_HMAC_SIGNATURE",
  "state": 3
}

Field	Type	Description
payOrderId	string	HashNut order ID
merchantOrderId	string	Your unique order identifier
accessSign	string	HMAC-SHA256 signature for querying the order
state	integer	New order state. See Order States

Notification Headers

The notification request includes HMAC signing headers (same format as Authentication):

Header	Description
hashnut-request-uuid	UUID for this notification
hashnut-request-timestamp	Unix timestamp (milliseconds)
hashnut-request-sign	Base64-encoded HMAC-SHA256 signature of uuid + timestamp + body

Signature Verification

DANGER

Always verify the hashnut-request-sign header before processing a notification. Accepting unverified notifications exposes your system to spoofing attacks.

Verification steps:

1. Read the hashnut-request-uuid, hashnut-request-timestamp, and hashnut-request-sign headers.
2. Read the raw request body as a string.
3. Concatenate: signString = uuid + timestamp + body
4. Compute base64( hmac_sha256( secretKey, signString ) ) using your Secret Key.
5. Compare the result with the received hashnut-request-sign.

Recommended Merchant Workflow

Upon receiving a notification:

1. Verify the header signature as described above.
2. Query the full order details using the Query Order API with the payOrderId, merchantOrderId, and accessSign from the notification body.
3. Update your internal order status based on the query result.
4. Return the string success to acknowledge receipt.

TIP

Do not rely solely on the state field in the notification for business logic. Always call the Query Order API to get the complete and authoritative order data (amount, transaction hash, etc.).

Required Response

Your Notify URL endpoint must return the plain text string success (HTTP 200) to acknowledge receipt.

HTTP/1.1 200 OK
Content-Type: text/plain

success

WARNING

If your endpoint does not return "success", HashNut treats the notification as failed and retries delivery.

Retry Policy

Attempt	Delay After Previous
1st retry	15 seconds
2nd retry	30 seconds
3rd retry	1 minute
4th retry	5 minutes
5th retry	30 minutes
6th retry	1 hour
7th retry	6 hours

After 7 retries (approximately 8 hours total), HashNut stops retrying. You can use Query Order to poll the current state if you missed notifications.

Notify URL vs Callback URL

These two URLs serve completely different purposes. Do not confuse them.

	Notify URL	Callback URL
Direction	HashNut backend --> Your backend	Customer browser --> Your frontend
Purpose	Server-to-server webhook notification	Frontend redirect after payment
Transport	HTTP POST with JSON payload	Browser redirect (302 or JS redirect)
Auth	Header HMAC signing	No signature
Reliability	Retried on failure	Single redirect, no retry
Example URL	https://api.yoursite.com/api/notify	https://yoursite.com/payment-result

TIP

Always implement the Notify URL for reliable order state tracking. The Callback URL is optional and is only used to improve the customer's frontend experience after payment.