Webhook qabul qilish: ishonchli qiluvchi besh qism
Webhook qabul qilish birinchi qarashda eng oson vazifalardan biri. Endpoint yozasiz, tashqi xizmat unga POST qiladi, siz ma'lumotni bazaga yozasiz. Besh qator kod.
Bu kod ishlaydi — sinovda. Ishlab chiqarishda esa savollar boshlanadi: bir xil hodisa ikki marta kelsa nima bo'ladi? Kechroq yuborilgan eski hodisa yangisidan keyin kelsa? Kimdir sizning endpointingizga soxta so'rov yuborsa?
Bu maqolada webhook qabul qiluvchining beshta qismini ko'rib chiqamiz. Ularning har biri ixtiyoriy emas.
1. Imzoni tekshirish
Webhook endpointi — bu internetdagi ochiq eshik. Uning manzilini bilgan har kim unga so'rov yuborishi mumkin.
Shuning uchun jiddiy xizmatlar har so'rovga imzo qo'shadi. Uni tekshirmasangiz, kimdir sizga "to'lov muvaffaqiyatli" degan soxta hodisa yuborishi mumkin.
import crypto from 'node:crypto'
function verify(rawBody: Buffer, signature: string, secret: string) {
const expected = crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('hex')
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signature),
)
}Ikkita muhim tafsilot bor va ikkalasi ham ko'p unutiladi.
Birinchisi — xom tanani ishlatish kerak. Agar framework JSON'ni parse qilib, keyin siz uni qayta JSON.stringify qilsangiz, bo'shliqlar va maydon tartibi o'zgaradi va imzo mos kelmaydi. Shuning uchun webhook marshrutida tananing xom shaklini saqlab qolish kerak.
Ikkinchisi — doimiy vaqtli taqqoslash. Oddiy === taqqoslash qancha belgi mos kelganiga qarab turlicha vaqt oladi va bu nazariy jihatdan imzoni tanlab olishga yo'l ochadi.
Uchinchi qo'shimcha: imzo bilan birga vaqt tamg'asi kelsa, uni ham tekshiring. Eski so'rovni qayta yuborish hujumidan himoya qiladi — masalan besh daqiqadan eski hodisalarni rad eting.
2. Tez javob berish
Eng ko'p uchraydigan arxitektura xatosi — webhook ichida butun ishni bajarish.
app.post('/webhooks/payment', async (c) => {
const event = await c.req.json()
await updateOrder(event) // baza
await sendReceiptEmail(event) // tashqi xizmat
await notifyWarehouse(event) // yana bitta tashqi xizmat
return c.text('ok')
})Muammo shundaki, jo'natuvchi xizmat odatda javobni bir necha soniya kutadi. Agar elektron pochta xizmati sekinlashsa, siz javob berolmaysiz, jo'natuvchi buni nosozlik deb hisoblaydi va hodisani qayta yuboradi. Endi sizda ikkita bir xil hodisa bor.
To'g'ri shakl — qabul qilish va qayta ishlashni ajratish:
app.post('/webhooks/payment', async (c) => {
const raw = await c.req.arrayBuffer()
if (!verify(Buffer.from(raw), c.req.header('x-signature'), SECRET)) {
return c.text('invalid signature', 401)
}
await db.insert(webhookEvents).values({
provider: 'payment',
eventId: JSON.parse(...).id,
payload: JSON.parse(...),
}).onConflictDoNothing()
return c.text('ok') // darhol
})Qabul qiluvchi faqat ikkita ish qiladi: imzoni tekshiradi va hodisani saqlaydi. Qolganini fon ishchisi bajaradi.
Bu ajratish yana bitta foyda beradi: qayta ishlashda xato chiqsa, hodisa yo'qolmaydi. U bazada turadi va siz uni qayta ishga tushira olasiz.
3. Idempotentlik
Har bir webhook jo'natuvchi ertami-kechmi bir xil hodisani ikki marta yuboradi. Bu nosozlik emas — bu ularning kafolat modeli: "kamida bir marta yetkazamiz".
Himoya bazada bo'lishi kerak, kodda emas:
create table webhook_events (
id uuid primary key default gen_random_uuid(),
provider text not null,
event_id text not null,
payload jsonb not null,
processed_at timestamptz,
received_at timestamptz not null default now(),
unique (provider, event_id)
);unique (provider, event_id) — butun himoya shu qatorda. Ikkinchi marta kelgan hodisa onConflictDoNothing bilan jimgina tashlanadi.
provider ustuni ham kerak: turli xizmatlar bir xil identifikator formatini ishlatishi mumkin va ular to'qnashmasligi kerak.
Agar jo'natuvchi hodisa identifikatorini umuman bermasa — bu kamdan-kam, lekin uchraydi — o'zingiz tuzing: tananing xeshi va vaqt tamg'asidan. Bu mukammal emas, lekin takroriy yuborishning aksariyatini tutadi.
4. Tartibsiz kelgan hodisalar
Bu eng ko'p e'tibordan chetda qoladigan muammo.
Webhook'lar kelgan tartibda emas yetib kelishi mumkin. "Buyurtma to'landi" hodisasi "buyurtma yaratildi" dan oldin kelishi mumkin — masalan birinchisi qayta yuborilgan bo'lsa.
Oddiy yechim: har hodisada versiya yoki vaqt tamg'asi bo'ladi, va siz eskisini qo'llamaysiz.
await db.update(orders)
.set({ status: event.status, statusUpdatedAt: event.occurredAt })
.where(and(
eq(orders.id, event.orderId),
lt(orders.statusUpdatedAt, event.occurredAt), // faqat yangiroq bo'lsa
))Shart bajarilmasa, yangilanish sodir bo'lmaydi va eski hodisa jimgina e'tiborsiz qoladi. Aynan kerakli xatti-harakat.
Agar tartib juda muhim bo'lsa, ikkinchi yo'l bor: hodisani saqlab qo'yib, kutilgan oldingi hodisa kelguncha qayta ishlamaslik. Lekin bu murakkabroq va ko'p holatda ortiqcha — versiya taqqoslash odatda yetarli.
5. Ko'rinuvchanlik
Webhook — bu ko'rinmas oqim. U buzilganini sizga hech kim aytmaydi; siz buni faqat mijoz shikoyat qilganda bilasiz.
Men uchta narsani kuzataman:
- Qayta ishlanmagan hodisalar soni —
processed_at is nullva besh daqiqadan eski. Nol bo'lishi kerak. - Imzo xatolari soni — nol bo'lishi kerak. Nolga teng bo'lmasa, yo sir noto'g'ri, yo kimdir sizni sinab ko'ryapti.
- Oxirgi hodisa yoshi — agar odatda soatiga o'nlab hodisa kelsa va uch soatdan beri hech narsa kelmagan bo'lsa, ehtimol jo'natuvchi tomonda muammo bor.
Uchinchisi ayniqsa foydali, chunki u hech narsa sodir bo'lmayotganini tutadi — bu esa xatolardan ko'ra ko'proq e'tibordan chetda qoladi.
Bundan tashqari, xom tanani saqlab qo'yish odatini qiling. Diskda joy arzon, muammoni tekshirishda esa "aynan nima kelgan edi?" degan savolga javob bebaho bo'ladi.
Yig'ib aytganda
Ishonchli webhook qabul qiluvchi shunday ishlaydi:
- Xom tanani oladi va imzoni doimiy vaqtda tekshiradi.
- Hodisani
unique (provider, event_id)cheklovi bilan saqlaydi. - Darhol
200qaytaradi. - Fon ishchisi qayta ishlaydi, versiya bo'yicha eskisini tashlab yuboradi.
- Uchta son kuzatiladi.
Bu ro'yxatda hech qanday murakkab texnologiya yo'q — bitta jadval va bitta fon ishchisi yetadi. Lekin bu beshta qismning har biri o'z o'rnida bo'lmasa, muammo albatta chiqadi. Va webhook muammolarining eng yomon tomoni shundaki, ular jimgina yuz beradi: hech narsa qulamaydi, shunchaki ma'lumot noto'g'ri bo'lib qoladi.