xpayment вебхук қолтаңбасын HMAC-SHA256 арқылы тексеріңіз: Node.js, Go және Python мысалдары, secret сақтау және қауіпсіз өңдеу.
Ашық эндпоинт жалған немесе қайта жіберілген сұраныс алуы мүмкін. xpayment әр жеткізілімді HMAC қолтаңбасымен аутентификациялайды. Өңдегіш оқиғаны талдамай және тапсырысты өзгертпей тұрып қолтаңбаны тексеруі керек.
Дұрыс қолтаңба нақты body-ге жазылым secret-ін білетін тарап қол қойғанын дәлелдейді. Ол сұраныстың жаңалығын дәлелдемейді: replay-ден әр delivery_id мәнін бір рет қана өңдеу арқылы бөлек қорғаныңыз.
Қолтаңба боевой және тест вебхуктары үшін бірдей: sandbox-та өңдеушіңізді дәл солай тексересіз. Дене пішімі мен қайталау ережелері вебхук нұсқаулығында сипатталған.
Әр әрекет үшін xpayment мынаны есептейді:
lowercase_hex(HMAC-SHA256(subscription_secret, exact_raw_body))
64 таңбалы digest sha256= префиксінсіз жіберіледі:
X-xPayment-Signature: aeafc0dcd86de4d4d376f525be2b1175520c2818c93938ec8d069957c63a373b
Байттарды дәл алынған күйінде хештеңіз. JSON-ды талдап, қайта сериализациялау бос орындарды, кілттер ретін немесе сандар пішімін өзгертуі мүмкін, сондықтан қолтаңба сәйкес келмейді.
Бұл алгоритмнің өзін тексеру, сондықтан төмендегі дене жеңілдетілген: нақты вебхуктарда created_at өрісінен кейін тағы бір өріс бар — environment (live немесе sandbox). Дәл алған байттарыңызға қол қойып, тексеріңіз және денені өрістерінен қайта жинауға тырыспаңыз.
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"}
Күтілетін қолтаңба:
aeafc0dcd86de4d4d376f525be2b1175520c2818c93938ec8d069957c63a373b
Secret-ті ешқайда жібермей, нәтижені жергілікті тексеруге болады:
printf '%s' '<жоғарыдағы дәл JSON>' | openssl dgst -sha256 -hmac 'qwerty123'
Қайталау кезінде attempt_number өзгереді, ал delivery_id сақталады. Body өзгергендіктен, xpayment әр әрекетке жаңа қолтаңба есептейді.
Жоқ немесе пішімі қате қолтаңбаны қабылдамаңыз, digest-ті бастапқы body арқылы қайта есептеп, мәндерді тұрақты уақытта салыстырыңыз.
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
}
// Body-ді талдап, delivery_id-ді идемпотентті қабылдап, жауап береміз.
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
Өңдеу реті әрқашан бірдей: қолтаңбаны тексеру -> JSON-ды талдау -> delivery_id мәнін атомарлы алу -> GET /v2/payments/{payment_id} арқылы төлемді сұрау -> өзгерісті қолдану -> 2xx қайтару. 2xx емес жауап xpayment жүйесіне жеткізуді қайталау керегін білдіреді.
Кемінде 32 кездейсоқ байт, яғни 64 hex-таңба жасаңыз:
openssl rand -hex 32
Әр жазылымға бөлек secret қолданып, оны құпиялар менеджерінде немесе орта айнымалысында сақтаңыз.
Мәнді жазылымды жасаған кезде сақтаңыз. Жазылымдар тізімі мен жаңарту жауаптары оны кейін көрсетпейді.
Өндірістік ортада бос secret пайдаланбаңыз. Backend оны қабылдап, HMAC жасайды, бірақ белгілі бос кілтпен жасалған қолтаңбаны кез келген адам қайталай алады.
Кабинет пен жалпыға қолжетімді API қазір бар жазылымның secret мәнін өзгерте алмайды. Оны ауыстыру үшін жаңа secret-пен жаңа жазылым жасаңыз, өңдеушіңіз екі мәнді де қабылдайтынша күтіңіз де, ескі жазылымды жойыңыз. Сонда оқиғаларды жоғалтпайсыз және екі рет өңдемейсіз: delivery_id және (payment_id, event) жұбы бойынша дубльдерді алып тастаңыз.
Sender әр әрекетте жазылымның ағымдағы secret мәнін оқиды. Жазылымның secret мәні әкімшілік жолмен өзгертілсе, кезектегі жеткізілімдер мен кейінгі қайталаулар жаңа мәнмен қол қойылады; жіберіліп жатқан сұраныста ескі қолтаңба қалуы мүмкін.
Қабылдайтын эндпоинтті әрқашан HTTPS арқылы жариялаңыз. Қазір xpayment жазылым URL-інің бос емес екенін ғана тексереді және схемаға шектеу қоймайды.
Қолтаңбаны тексеру body-ді аутентификациялайды, ал delivery_id бойынша атомарлы идемпотенттілік қайталау мен replay-ден қорғайды. Payload пен қайталау ережелері вебхук жеткізу нұсқаулығында берілген, ал өңдеушіңізді нақты ақшасыз sandbox-та тексеруге болады.