Вебхук қолтаңбасын тексеру | xpayment

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 арқылы қайта есептеп, мәндерді тұрақты уақытта салыстырыңыз.

Node.js және Express

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 })
})

Go

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)
}

Python және Flask

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 жүйесіне жеткізуді қайталау керегін білдіреді.

Secret-ті басқару

Кабинет пен жалпыға қолжетімді API қазір бар жазылымның secret мәнін өзгерте алмайды. Оны ауыстыру үшін жаңа secret-пен жаңа жазылым жасаңыз, өңдеушіңіз екі мәнді де қабылдайтынша күтіңіз де, ескі жазылымды жойыңыз. Сонда оқиғаларды жоғалтпайсыз және екі рет өңдемейсіз: delivery_id және (payment_id, event) жұбы бойынша дубльдерді алып тастаңыз.

Sender әр әрекетте жазылымның ағымдағы secret мәнін оқиды. Жазылымның secret мәні әкімшілік жолмен өзгертілсе, кезектегі жеткізілімдер мен кейінгі қайталаулар жаңа мәнмен қол қойылады; жіберіліп жатқан сұраныста ескі қолтаңба қалуы мүмкін.

Қабылдайтын эндпоинтті әрқашан HTTPS арқылы жариялаңыз. Қазір xpayment жазылым URL-інің бос емес екенін ғана тексереді және схемаға шектеу қоймайды.

Қолтаңбаны тексеру body-ді аутентификациялайды, ал delivery_id бойынша атомарлы идемпотенттілік қайталау мен replay-ден қорғайды. Payload пен қайталау ережелері вебхук жеткізу нұсқаулығында берілген, ал өңдеушіңізді нақты ақшасыз sandbox-та тексеруге болады.