Webhooks & asynchronous events#

Provider buyurtma holati o‘zgarganda Zayunoga imzolangan event yuboradi. Provider action ID, event ID va status haqiqiy ma’lumotlardan olinadi.

Canonical endpoint#

POST https://api.zayuno.uz/api/v1/webhooks/{providerSlug}
Content-Type: application/json
x-zayuno-signature: <HMAC_SHA256_HEX>

providerSlug URL ichida beriladi. Event ichidagi providerSlug ham shu providerga tegishli bo‘lsin. Yangi integratsiyalar canonical route’dan foydalanadi.

Event schema va namuna#

Aniq JSON, required fieldlar va response generated webhook reference ichida.

• eventId: shu hodisa uchun barqaror ID; retry’da almashtirmang.
• eventType: contractga mos event turi.
• providerSlug: ro‘yxatdan o‘tgan provider.
• actionId yoki externalActionId: to‘g‘ri buyurtmani aniqlash uchun.
• timestamp: hodisa vaqti, ISO 8601.
• newStatus va newPaymentStatus: o‘zgarayotgan normalized holatlar.

Faqat backend tasdiqlagan statusni yuboring. To‘lov uchun PAID qiymati provider xabari hisoblanadi; u bank settlement’i mustaqil tekshirilganini anglatmaydi.

Raw body va HMAC#

HMAC-SHA256 hex digest’ni ZAYUNO_WEBHOOK_SECRET bilan aynan yuboriladigan rawBody ustida hisoblang. x-zayuno-signature headerga yozing. Timestampni signature stringiga qo‘shmang. Tayyor TypeScript signing misoli.

Delivery va retry#

HTTP natijasini tekshiring. Timeout yoki vaqtinchalik server xatosida o‘sha eventId bilan cheklangan backoff retry qiling. 401 da key va imzoni tuzatmasdan doimiy retry qilmang.

Event statusi o‘zgarsa yangi eventId bering. Bir xil eventni qayta yuborish takroriy buyurtma yaratmasligi kerak. Idempotency event va action darajasida alohida ahamiyatga ega.

Certification talabi va buyurtmaga qo‘llanilishi (isProcessed)#

Transactional providerlar certificationdan o‘tishi uchun faqatgina lokal HMAC tekshiruvini bilishi yetarli emas. Avtomatlashtirilgan runner quyidagilarni tekshiradi:

1. POST /actions orqali yaratilgan har bir test buyurtmasi uchun provider backend Zayunoga action.status_updated webhookini jo‘natishi kerak.
2. Zayuno webhookni qabul qilib, imzosi to‘g‘ri ekanligini tasdiqlaydi (isVerified: true) va bazadagi test buyurtmasining statusini yangilaydi (isProcessed: true).
3. Faqat isProcessed: true bo‘lgan webhooklargina certification runner tomonidan muvaffaqiyatli yetkazib berish va qayta ishlash dalili sifatida qabul qilinadi.

Diagnostika#

So‘rovlar jurnali va troubleshooting yordamida provider slug, trace ID, signature header nomi va timestamp’ni tekshiring. Raw secretlarni diagnostika xabariga qo‘shmang.