Қысқаша
Алдымен кабинеттегі webhook журналын ашыңыз: біз хабарламаны жібердік пе, сервер қандай жауап қайтарды — бәрі сонда жазулы. Журналда «жіберілді, бірақ жауап жоқ» немесе 401/403 тұрса, мәселе сіздің адресіңізде. Ең жиі кездесетін себеп — webhook адресі авторизациямен жабық: сайтыңыздың басты паролі, IP тізімі, Cloudflare қорғанысы немесе VPN бізді ішке кіргізбейді. Біз кәдімгі сыртқы клиент сияқты келеміз, ешқандай логин-пароль жібермейміз.
Симптом бойынша
| Не көріп тұрсыз | Ықтимал себебі | Не істеу керек |
|---|---|---|
| Журналда бірде-бір жазба жоқ | Адрес мүлде қосылмаған немесе бұл оқиға таңдалмаған | Кабинет → Интеграциялар → адресті және оқиға тізімін тексеріңіз |
| Журналда «жіберілді», жауап 401/403 | Адрес авторизациямен жабық | Дәл сол жолды ашық қалдырыңыз |
| Жауап 404 | Адрес жолы қате немесе маршрут тіркелмеген | Толық адресті браузерге емес, curl-мен тексеріңіз |
| Жауап 301/302 | Басқа жерге қайта бағыттау — біз ұстамаймыз | Соңғы адресті webhook ретінде жазыңыз |
| Жауап 500 | Сіздің өңдеушіңіз құлап жатыр | Өз журналыңызды қараңыз |
| Жауап уақыты біткен (timeout) | Өңдеу тым ұзақ | Алдымен 200 қайтарыңыз, жұмысты кейін істеңіз |
| Хабарлама келеді, бірақ код оны қабылдамайды | Қолтаңба сәйкес келмейді | Төмендегі 5-қадамды қараңыз |
Диагностика реті
Ретті бұзбаңыз — әр қадам келесісін мағыналы етеді.
1. Кабинеттегі журналды қараңыз. Интеграциялар бөлімінде әр жіберілім жазылады: оқиға түрі, уақыты, серверіңіздің HTTP жауабы. Егер жазба мүлде болмаса, біз жібермегенбіз — демек счёттың күйі әлі өзгермеген немесе адрес қосылмаған. Егер жазба бар да, жауап сәтсіз болса, мәселе сіздің жағыңызда.
2. Адрес жария қолжетімді ме? Бұл ең жиі кездесетін себеп. Webhook адресі интернеттен кез келген клиент үшін ашық болуы керек. Бізде сіздің паролііңіз, токеніңіз, VPN-іңіз жоқ.
Тексеру: өзіңіздің серверіңізден емес, сырттан сұрау жіберіңіз.
curl -i -X POST https://sizdin-domen.kz/webhooks/qutpay -d '{}'401, 403, 302 немесе байланыс мүлде орнамаса — біз де дәл солай кіре алмаймыз. Жиі кездесетін кедергілер: сайтқа қойылған басты пароль (basic auth), әкімшілік панельдің қорғанысы, WAF немесе Cloudflare ережесі, IP бойынша ақ тізім, staging орта.
Шешімі — бүкіл сайтты ашу емес, тек осы бір жолды авторизациясыз қалдыру. Қауіпсіздікті қолтаңба тексеруі қамтамасыз етеді, ол пароль орнына жүреді.
3. https па және нақты домен бе? Продакшенде тек https қабылданады, домен нақты болуы керек. IP адрес, уақытша туннель адрестері (ngrok сияқты) қабылданбайды. Сертификат жарамды болсын: мерзімі өткен немесе өзі қол қойған сертификат байланысты үзеді.
4. Қайта бағыттауды алып тастаңыз. Біз 307 және 308 бағыттауларын тек сол адрестің өзіне ұстаймыз — мысалы http → https немесе соңындағы қиғаш сызық. Басқа домен немесе басқа жолға апаратын бағыттау ұсталмайды. Сондықтан webhook ретінде соңғы, нақты адресті жазыңыз: www болса www-мен, қиғаш сызық керек болса сызығымен.
5. Қолтаңба тексеруін тексеріңіз. Кейде хабарлама жетеді, бірақ өңдеуші оны қабылдамай тастайды. Қолтаңба HMAC-SHA256(secret, timestamp + "." + rawBody) түрінде есептеледі, hex, sha256= префиксімен. Ең жиі қате — денені JSON-ға айналдырып, сосын қайта мәтінге түрлендіріп тексеру. Өзгертілмеген байт күйіндегі денені қолданыңыз.
6. Сервер 2xx қайтарады ма? Біз 2xx-тен басқасының бәрін сәтсіз деп есептейміз. Өңдеу ұзаққа созылатын болса, алдымен 200 қайтарып, жұмысты фонда істеңіз.
Қайталау
2xx емес жауап берсеңіз немесе жауап мүлде келмесе, біз хабарламаны 11 рет қайталаймыз. Аралық 10 секундтан басталып, бір сағатқа дейін өседі. Яғни серверіңіз бір сағатқа құласа да, қалпына келгенде хабарлама жетеді — қолмен ештеңе істеудің қажеті жоқ.
Бірақ осы себепті өңдеуіңіз идемпотентті болуы керек: бір оқиға бірнеше рет келуі мүмкін. (invoice.id, status) жұбын кілт ретінде алып, бұрын өңдегеніңізді екінші рет өңдемеңіз.
webhook.site арқылы сынау
Мәселе бізде ме, сізде ме — екі минутта анықтауға болады.
- webhook.site ашасыз, ол сізге уақытша адрес береді
- Кабинет → Интеграциялар → сол адресті webhook ретінде қосасыз
- Sandbox режимінде счёт жасап, төлемді симуляциялайсыз
- webhook.site бетінде хабарлама пайда болды ма?
Пайда болса — біз дұрыс жіберіп тұрмыз, мәселе сіздің серверіңізде: адрес жабық, маршрут жоқ немесе код қате. Пайда болмаса — адрес тізімін, оқиға таңдауын тексеріп, қолдауға жазыңыз.
Сынау біткен соң уақытша адресті өшіруді ұмытпаңыз: ол жария, оған келген деректі кез келген адам көреді.
Жиі жіберілетін қателер
- Webhook адресін браузерде ашып тексеру. Браузер GET жібереді, ал біз POST жібереміз. GET жауап берді дегеніміз POST жауап береді дегенді білдірмейді.
- Локалдағы адресті жазу.
localhost,127.0.0.1немесе жергілікті желі адресі сырттан көрінбейді. - Оқиға тізімін тарылтып қою. Тек
invoice.paidтаңдап қойып, сосынinvoice.expiredнеге келмейді деп ойлау. - Тек webhook-қа сүйену. Кідіріске сезімтал сценарийде webhook-пен қатар счёт күйін де сұрап тұрған дұрыс.
- Тест пен нақты режимді шатастыру. Sandbox-та бір адрес, live-та басқа адрес тұрса, бір режимде істеп, екіншісінде істемейді.
Жиі қойылатын сұрақтар
Webhook орнына күйді өзім сұрасам бола ма? Болады, бірақ екеуін қатар жүргізген дұрыс: webhook жылдам, сұрау сенімді.
Хабарлама бірнеше рет келді — бұл қате ме? Жоқ, бұл қалыпты. Қайталау механизмі осылай жұмыс істейді. Өңдеуіңіз идемпотентті болса, зияны жоқ.
Құпияны жоғалтып алдым, көру мүмкін бе? Жоқ, құпия бір рет қана көрсетіледі. Кабинеттен жаңасын жасаңыз да, кодтағы мәнді жаңартыңыз.
Сервер уақытша құлап тұрса, төлемдер жоғала ма? Жоқ. Қайталау бір сағатқа дейін созылады, ал счёттардың күйі бізде сақталады — кез келген уақытта API арқылы оқи аласыз.
Webhook қанша уақыт ішінде келеді? Клиент төлегеннен кейін әдетте бес секунд ішінде. Кешігу болса: Счёт pending күйінде тұрып қалды.