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

> Webhook — негізгі әдіс, бірақ жеткізу кепілдігі абсолютті емес. Кідіріске сезімтал сценарийлерде екеуін қатар жүргізу керек: қалай, қандай жиілікпен және неге бұл артық жұмыс емес.

## Қысқаша

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

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

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

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

| | Webhook | Күйді сұрау (polling) |
|---|---|---|
| Кім бастайды | Біз | Сіз |
| Сізге не керек | Сырттан қолжетімді `https` адрес | Тек шығыс интернет |
| Кідірісі | Әдетте 5 секунд ішінде | Сұрау жиілігіңізге тең |
| Жеткізу кепілдігі | Жоғары, бірақ абсолютті емес | Сіз сұраған сайын жауап аласыз |
| Қолтаңба тексеру | Керек | Керек емес |
| Серверсіз жұмыс істей ме | Жоқ | Иә |

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

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

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

| Счёттың жасы | Тексеру жиілігі |
|---|---|
| 3 минуттан жас | Әр айналымда, яғни шамамен әр 3 секунд |
| 30 минутқа дейін | Шамамен 20 секунд сайын |
| Одан ескі | Шамамен 90 секунд сайын |

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

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

Толығы: [Webhook баптау](/kb/webhook-setup).

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

Мына сценарийлерде тек 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)` жұбы бойынша екінші рет өңдемеңіз. Толығы: [Идемпоттылық](/kb/idempotency).

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

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

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

| Счёттың жасы | Сұрау жиілігі |
|---|---|
| Алғашқы 3 минут | 3-5 секунд сайын |
| 3-30 минут | 20-30 секунд сайын |
| Одан ескі | 1-2 минут сайын немесе мүлде тоқтату |

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

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

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

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

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

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

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

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

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

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

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

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