Verify xpayment webhook signatures with HMAC-SHA256 examples for Node.js, Go, and Python, and learn how to store and replace webhook secrets.
A public endpoint can receive forged or replayed requests. xpayment authenticates each delivery with an HMAC signature. Your handler must verify that signature before parsing the event or changing an order.
A valid signature proves that the exact body was signed by someone who knows the subscription secret. It does not prove freshness: prevent replays separately by processing each delivery_id only once.
The signature is the same for live and test webhooks: in the sandbox you check your handler exactly the same way. The body format and retry rules are described in the webhook guide.
For every attempt, xpayment calculates:
lowercase_hex(HMAC-SHA256(subscription_secret, exact_raw_body))
The 64-character digest is sent without a sha256= prefix:
X-xPayment-Signature: aeafc0dcd86de4d4d376f525be2b1175520c2818c93938ec8d069957c63a373b
Hash the bytes exactly as received. Parsing and re-serializing JSON can change whitespace, key order, or number formatting and therefore produce a different signature.
This checks the algorithm itself, so the body below is simplified: in real webhooks there is one more field after created_at, environment (live or sandbox). Sign and verify exactly the bytes you received, and never try to rebuild the body from its fields.
Secret: qwerty123
{"event":"payment.refunded","event_version":"1","delivery_id":"c09a3647-7822-4899-8401-3857cbd5bf68","attempt_number":1,"source":"xpayment","payment_id":"65cd0d84-5f66-4763-94d2-1b8e1ba68347","merchant_order_id":"qweasdxzc","created_at":"2026-06-27T10:24:04.104055991+05:00"}
Expected signature:
aeafc0dcd86de4d4d376f525be2b1175520c2818c93938ec8d069957c63a373b
You can reproduce it locally without sending the secret anywhere:
printf '%s' '<exact JSON above>' | openssl dgst -sha256 -hmac 'qwerty123'
On a retry, attempt_number changes while delivery_id stays the same. Because the body changes, xpayment calculates a new signature for every attempt.
Reject a missing or malformed signature, recompute the digest from the raw body, and compare in constant time.
const crypto = require("crypto")
function validSignature(rawBody, signature, secret) {
if (!/^[0-9a-f]{64}$/.test(signature || "")) return false
const received = Buffer.from(signature, "hex")
const expected = crypto.createHmac("sha256", secret).update(rawBody).digest()
return crypto.timingSafeEqual(received, expected)
}
app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf } }))
app.post("/webhook", async (req, res) => {
const signature = req.get("X-xPayment-Signature")
if (!validSignature(req.rawBody, signature, process.env.WEBHOOK_SECRET)) {
return res.status(401).end()
}
await acceptIdempotently(req.body)
return res.status(200).json({ ok: true })
})
func validSignature(body []byte, signature, secret string) bool {
received, err := hex.DecodeString(signature)
if err != nil || len(received) != sha256.Size {
return false
}
mac := hmac.New(sha256.New, []byte(secret))
_, _ = mac.Write(body)
return hmac.Equal(received, mac.Sum(nil))
}
func handler(w http.ResponseWriter, r *http.Request) {
body, err := io.ReadAll(r.Body)
if err != nil {
http.Error(w, "invalid body", http.StatusBadRequest)
return
}
if !validSignature(
body,
r.Header.Get("X-xPayment-Signature"),
os.Getenv("WEBHOOK_SECRET"),
) {
w.WriteHeader(http.StatusUnauthorized)
return
}
// Decode body, accept delivery_id idempotently, then acknowledge.
w.WriteHeader(http.StatusOK)
}
import hashlib, hmac, re
from flask import request
def valid_signature(raw_body: bytes, signature: str, secret: str) -> bool:
if re.fullmatch(r"[0-9a-f]{64}", signature or "") is None:
return False
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(signature, expected)
@app.post("/webhook")
def webhook():
raw_body = request.get_data()
signature = request.headers.get("X-xPayment-Signature", "")
if not valid_signature(raw_body, signature, WEBHOOK_SECRET):
return "", 401
accept_idempotently(request.get_json())
return {"ok": True}, 200
The processing order is always: verify signature -> parse JSON -> claim delivery_id atomically -> fetch the payment with GET /v2/payments/{payment_id} -> apply the change -> return 2xx. A non-2xx response tells xpayment to retry.
Generate at least 32 random bytes (64 hexadecimal characters):
openssl rand -hex 32
Use a different secret for every subscription and store it in a secret manager or environment variable.
Save it when creating the subscription. The public list and update responses do not reveal it later.
Never use an empty secret in production. The backend accepts one and still produces an HMAC, but anyone can reproduce a signature made with a known empty key.
The dashboard and the public API currently cannot change the secret of an existing subscription. To change it, create a new subscription with a new secret, wait until your handler accepts both values, and delete the old subscription. That way you neither lose events nor process them twice: deduplicate by delivery_id and by the pair (payment_id, event).
The sender reads the subscription’s current secret for each attempt. If the secret of a subscription is changed administratively, queued deliveries and later retries are signed with the new value; a request already in flight may still carry the old signature.
Always expose the receiving endpoint over HTTPS. xpayment currently validates only that a subscription URL is non-empty; it does not enforce the URL scheme for you.
Signature verification authenticates the body, while atomic idempotency on delivery_id protects against retries and captured-request replays. See the webhook delivery guide for the payload and retry behavior, and test your handler without real money in the sandbox.