Webhook пен күйді сұрау: қайсысы қашан

Қысқаша

Webhook — негізгі әдіс. Клиент төлегенде біз сіздің адресіңізге өзіміз хабарлаймыз, сіз ештеңе сұрап отырмайсыз.

Бірақ webhook — желі арқылы жүретін нәрсе, ал желі мінсіз емес: сіздің серверіңіз қайта жүктеліп жатқан болуы мүмкін, хостинг жауап бермей қалуы мүмкін. Сондықтан кідіріске сезімтал сценарийлерде (шлагбаум, вендинг, касса, тікелей эфир) webhook-ты күйді сұраумен қатар жүргізіңіз: webhook белгілі уақытта келмесе, GET /api/v1/invoices/{id} арқылы өзіңіз сұраңыз.

Онлайн-дүкен, CRM, есеп беру сияқты бірнеше секундтық кідіріс маңызды емес жерлерде — тек webhook жеткілікті.

Екеуінің айырмашылығы

Webhook неге негізгі әдіс

Клиент төлегеннен кейін біздің poller Kaspi-ден күйді алады да, сол сәтте сізге хабарлайды. Іс жүзінде webhook әдетте 5 секунд ішінде келеді.

Poller счёттың жасына қарай жұмыс істейді — жаңа счёттар жиі тексеріледі:

Кезек ең жаңа счёттан басталады: клиент алдыңызда тұрған счёт ешқашан кешегі счёттың артында кезекте тұрмайды.

Webhook 2xx жауап алмаса, 11 рет қайталанады — 10 секундтан басталып, 1 сағатқа дейін өсетін кідіріспен. Ал адресіңіз қатарынан қате бере берсе, ол уақытша тоқтатылады (5 сәтсіздік — 5 минут, 10 — 30 минут, 20 — 2 сағат, 50 — мүлде өшіріледі). Бұл — сіздің серверіңізді де, кезекті де қорғайтын механизм, бірақ мұны білу керек: адрес тоқтатылып тұрғанда webhook мүлде келмейді.

Толығы: Webhook баптау.

Қашан екеуін қатар жүргізу керек

Мына сценарийлерде тек webhook-қа сүйенбеңіз:

• Шлагбаум, турникет, есік. Клиент машинасында отыр, 30 секунд күту қолайсыз
• Вендинг автоматы. Адам автоматтың алдында тұр
• Офлайн касса. Кезек тұр
• Тікелей эфир, жылдам сату. Бірнеше ондаған секунд — сатылым жоғалту
• Жеткізу курьері. Есік алдында тұр

Ортақ белгісі: адам күтіп тұр және бірнеше ондаған секунд қымбат.

Мына жерлерде тек webhook жеткілікті:

• Интернет-дүкен (тапсырыс кейін жиналады)
• CRM-де мәміле сатысын жылжыту
• Есеп беру, бухгалтерия
• Жазылымдық қызметке қолжетімділік ашу

Қалай қатар жүргізу керек

Реті қарапайым: webhook күтесіз, ол келмесе өзіңіз сұрайсыз.

1. Счёт жасайсыз, id аласыз
2. Клиентке QR немесе сілтеме көрсетесіз
3. Таймер қосасыз. Мысалы 5 секунд
4. Осы уақыт ішінде webhook келсе — бітті, сұраудың қажеті жоқ
5. Келмесе — GET /api/v1/invoices/{id} жіберіп, күйді оқисыз
6. Күй paid болса — жұмысты жалғастырасыз
7. Әлі pending болса — қайта күтесіз

Маңызды: webhook та, сұрау да бір нәтижеге әкеледі, сондықтан екеуі бір уақытта келуі мүмкін. Өңдеуіңіз идемпотентті болуы керек — (invoice.id, status) жұбы бойынша екінші рет өңдемеңіз. Толығы: Идемпоттылық.

Сұрау жиілігін қалай таңдау керек

«Жиірек сұрасам — жылдамырақ білемін» деген дұрыс емес: біздің poller Kaspi-ден күйді өз кестесімен алады, ал сіздің сұрауыңыз бізде бар мәліметті ғана қайтарады. Секундына он рет сұрау ештеңені жылдамдатпайды, тек 429 (rate_limited) алуға әкеледі.

Ақылға қонымды кесте:

Бұл біздің poller-дің кестесіне сәйкес келеді: жаңа счёттар бәрібір жиі тексеріледі, ескі счёттар үшін жиі сұраудың мәні жоқ.

Қосымша ережелер:

• Ашық счёттарды ғана сұраңыз. paid, cancelled, expired — соңғы күйлер, оларды қайта сұраудың қажеті жоқ
• Күтуге шек қойыңыз. Счёттың expiresAt өрісі өтіп кетсе, сұрауды тоқтатыңыз
• Тізімді бір сұраумен алыңыз. Жүздеген ашық счёт болса, әрқайсысын бөлек сұраудың орнына GET /api/v1/invoices арқылы тізімді алыңыз
• 429 келсе Retry-After тақырыбын қараңыз: Сұрау жиілігінің шектеулері

Тек сұрау жеткілікті бола ма

Иә, бола алады — егер сізде сырттан қолжетімді сервер болмаса (мысалы жергілікті кассалық бағдарлама, жабық желідегі жүйе). Бұл жағдайда webhook мүлде қосылмайды, сіз тек GET /api/v1/invoices/{id} арқылы жұмыс істейсіз.

Кемшілігі: сұраулар саны көбейеді және кідіріс сіздің жиілігіңізге тең болады. Артықшылығы: ешқандай кіріс адрес, қолтаңба тексеру, HTTPS сертификат керек емес.

Жиі қойылатын сұрақтар

Webhook келмесе, ол жоғалып кетті дегенді білдіре ме? Жоқ. Ол 11 рет қайталанады, яғни бір сағат бойы жетуге тырысады. Бірақ сіздің бизнесіңіз ол уақытты күте алмайтын болса, сұрау қажет.

Екеуі бірдей келсе, тапсырысты екі рет өңдеп қоямын ба? Идемпоттылық болса — жоқ. (invoice.id, status) жұбы бойынша тексеріңіз.

Сұрау тариф лимитін жей ме? Жоқ. Айлық лимит счёт саны бойынша есептеледі, сұраулар емес. Бірақ сұрау жиілігінің бөлек шектеуі бар, ол 429 береді.

Төлем баяу расталатын сияқты, сұрауды жиілетейін бе? Алдымен себебін тексеріңіз: Төлем баяу расталады. Жиілету көмектеспейді, өйткені шектеу Kaspi-ден күй алу жағында.

Қызметтің өзі жұмыс істеп тұрғанын қалай тексеремін? GET /api/v1/status эндпоинті бар: Қызмет күйін тексеру.