> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tungo.kz/llms.txt
> Use this file to discover all available pages before exploring further.

# Оқиғаларды алу (вебхуктар)

> Серверіңіздің мекенжайын қосыңыз, оқиғаларды таңдаңыз, қолтаңбаны тексеріңіз және қайталаулар мен қосарланған оқиғаларға дайын болыңыз.

Вебхук API-ді қайта-қайта сұраудан құтқарады: ұйымда бірдеңе болғанда Tungo серверіңіздің мекенжайына JSON бар POST-сұрауды өзі жібереді. Сіз мекенжайды қосасыз, оқиғаларды таңдайсыз және әр сұраудың қолтаңбасын тексеретін құпияны аласыз.

Мекенжайларды ұйымның иесі немесе әкімшісі платформа экрандарында қосады. Мұны API арқылы `webhooks.manage` құқығы бар кілтпен де жасауға болады, ол құқық тек барлық компанияға арналған кілтте бар.

Вебхуктарды автоматтандырулардың кіріс хуктарымен шатастырмаңыз. Вебхук — Tungo-дан сізге келетін оқиға. Кіріс хук — сіздің жүйеңізден Tungo-ға келіп, сценарийді іске қосатын оқиға: [Автоматтандыру деген не](https://docs.tungo.kz/kk/automations/overview.md) бетін қараңыз.

## Мекенжай қосу

**1. «Вебхуктар» бөлімін ашыңыз**

Кабинет мәзірінде **Платформа** сілтемесін басыңыз, **Вебхуктар** бөлімін таңдап, **Мекенжай қосу** батырмасын басыңыз.

**2. Сервердің мекенжайын көрсетіңіз**

Тек `https://` деп басталатын және интернеттен қолжетімді мекенжай жарайды. Ішкі желі мекенжайларын Tungo қабылдамайды.

**3. Оқиғаларды таңдаңыз**

Осы мекенжайға керек оқиғаларды белгілеңіз. Ештеңе таңдамасаңыз, бәрі келеді.

**4. Қолтаңба құпиясын көшіріп алыңыз**

Қосылғаннан кейін экран `whsec_…` түріндегі құпияны көрсетеді. Оны өз серверіңізде құпиясөз сияқты сақтаңыз.

Сол мекенжайды API арқылы қосу:

```sh theme={null}
curl -X POST "$TUNGO_API/v1/workspaces/$WS/webhooks/endpoints" \
  -H "x-api-key: $TUNGO_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://example.kz/tungo-events","event_types":["proposal.written"]}'
```

Жауапта мекенжайдың `id` мәні мен `secret` келеді. Кілтпен құпияны енді еш жерден оқи алмайсыз, оны тек ауыстыруға болады. Кабинетте құпияны кейін де көруге болады: мекенжай мәзірі, **Құпияны көрсету** тармағы.

## Қандай оқиғалар болады

Оқиға атаулары `event_types` өрісінде беріледі және `type` өрісінде келеді.

* 1С үшін құжаттар: `proposal.awaiting_approval`, `proposal.written`, `proposal.failed`, `proposal.rejected`.
* ЖИ-бухгалтердің кілт бойынша жауаптары: `chat.turn.completed`.
* Үзінділер мен ЭШФ-ларды талдау: `bank_statement.received`, `esf.incoming.received`, `batch.completed`, `batch.failed`.
* Автоматтандырулар: `automation.run.completed`, `automation.run.failed`, `automation.run.notice`, `automation.write_unknown`.
* Платформа балансы: `platform.balance_low`, `platform.balance_exhausted`, `platform.cap_threshold_reached`.
* Кілттер: `api_key.expiring`, `api_key.cap_reached`.
* Төлем және 1С-пен байланыс: `payment.succeeded`, `payment.failed`, `onec.connection.changed`.

Барлық оқиғаның денесі бірдей құрылған:

```json theme={null}
{
  "id": "evt_…",
  "type": "proposal.written",
  "created_at": "…",
  "workspace_id": "ws_…",
  "company_id": "co_…",
  "data": {}
}
```

`data` ішінде тек id-лер, тиынмен берілген сомалар, күйлер және уақыт жатады. Аттар, деректемелер және құжаттардың мәтіні онда жоқ. Толық мәліметті оқиғадағы id бойынша API-ден алыңыз. Әр оқиғаның `data` өрістері API анықтамасында және «Вебхуктар» бөлімінің «Оқиға түрлері» қойындысында сипатталған.

Мекенжайға қосымша `channels` — сценарий id-лерінің тізімін де беруге болады. Сонда оған тек осы сценарийлердің оқиғалары келеді, мысалы бір сценарийдің қорытындысы өз жүйеңізге. Бұл өріс тек API арқылы қолжетімді.

## Сынақ оқиғасын жіберу

Мекенжай мәзірінен **Тексеру жіберілімі** тармағын таңдаңыз. Мекенжайға түрі `ping`, ал `data` өрісі бос оқиға жіберіледі. Оған нақты оқиғалар сияқты қол қойылған, сондықтан сол арқылы қабылдауды да, қолтаңбаны да тексеру ыңғайлы. Нәтижені **Жеткізу әрекеттері** тармағынан қараңыз: онда серверіңіздің не деп жауап бергені көрінеді.

API арқылы сынақ оқиғасын `POST /v1/workspaces/{ws}/webhooks/endpoints/{id}/test` жібереді.

## Қолтаңбаны тексеру

Әр сұрау үш тақырыппен келеді: `webhook-id`, `webhook-timestamp` және `webhook-signature`. Оқиғамен бірдеңе істемес бұрын қолтаңбаны тексеріңіз. Әйтпесе мекенжайды білген кез келген адам сізге жалған оқиға жібере алады.

Қол нүктемен бөлінген үш бөліктен тұратын жолға қойылады: `webhook-id`, `webhook-timestamp` және сұраудың денесі. Дене дәл келген күйінде, JSON талдауына дейін алынады. Қолтаңба кілті — құпияның `whsec_` бөлігінен кейінгі, base64-тен кері кодталған бөлігі. Қолтаңба HMAC-SHA256 ретінде есептеледі және base64 түрінде кодталады.

```js theme={null}
import { createHmac, timingSafeEqual } from 'node:crypto'

// secret — whsec_…; headers — сұраудың тақырыптары; rawBody — дене жол түрінде, келген күйінде, JSON талдауына дейін.
function verifyWebhook(secret, headers, rawBody, nowSec = Date.now() / 1000) {
  const id = headers['webhook-id']
  const ts = headers['webhook-timestamp']
  if (Math.abs(nowSec - Number(ts)) > 300) return false // 5 минуттан ескі: бөгде сұраудың қайталануы
  const key = Buffer.from(secret.slice('whsec_'.length), 'base64')
  const want = createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest()
  // Тақырыпта қолтаңбалар бос орын арқылы: v1,<base64>. Құпия ауысқаннан кейін олар екеу.
  return headers['webhook-signature'].split(' ').some((s) => {
    const got = Buffer.from(s.split(',')[1] ?? '', 'base64')
    return got.length === want.length && timingSafeEqual(got, want)
  })
}
```

Қолтаңба сәйкес келмесе, 400 деп жауап беріңіз және ештеңе істемеңіз. Қолтаңба Standard Webhooks ашық келісіміне сай, сондықтан өз кодыңыздың орнына дайын кітапхананы алуға болады, мысалы npm-дегі `standardwebhooks`.

Құпия мекенжай мәзіріндегі **Құпияны қайта шығару** тармағымен немесе `POST …/endpoints/{id}/secret/rotate` сұрауымен ауыстырылады. Ауыстырғаннан кейін тағы бір тәулік бойы Tungo тақырыпқа екі қолтаңба қояды: жаңа құпиямен және бұрынғы құпиямен. Жоғарыдағы мысалдағыдай «кем дегенде біреуі сәйкес келді» деп тексеретін қабылдағыш ауысудан оқиғаларды жоғалтпай өтеді.

## Қайталаулар мен қосарланған оқиғалар

Серверіңіз 30 секунд ішінде кез келген 2xx кодымен жауап берсе, жеткізу сәтті деп есептеледі. Сондықтан бірден жауап беріңіз, ал ұзақ өңдеуді жауаптан кейін жасаңыз.

Жауап жоқ болса немесе ол басқа болса, Tungo жіберуді қайталайды: 5 секундтан, 5 минуттан, 30 минуттан, 2 сағаттан, 5 сағаттан кейін, содан соң алты рет 10 сағат сайын және тағы бір рет 5 сағаттан кейін. Барлығы шамамен үш тәулік ішінде 13 әрекет болады. Одан кейін оқиғаны қолмен жіберуге болады: «Оқиғалар» қойындысы, **Қайта жіберу** тармағы.

Қайталаулардың кесірінен бір оқиға екі рет келуі мүмкін. Қайталанған оқиғаның денесіндегі `id` сол күйінде болады, қосарланғандарды сол бойынша алып тастаңыз. Рет те кепілдендірілмейді: оқиғалар болған ретімен келмеуі мүмкін. `created_at` мәнін салыстырыңыз, ал өзекті күйді API арқылы оқыңыз.

## Мекенжай жауап бермесе

Бес тәулік қатарынан бірде-бір оқиға қабылдамаған мекенжайды Tungo өзі өшіреді. Тізімде оның күйі «Өшірулі» болады, оған жаңа оқиғалар жіберілмейді. Қабылдағышты жөндеп, мекенжайды қосыңыз: мекенжай мәзірі, **Қосу** тармағы немесе `"enabled": true` бар `PATCH` сұрауы.

Мекенжай өшірулі тұрғанда болған оқиғалар өздігінен келеді деп үміттенбеңіз. Жіберіп алғаныңызды API арқылы қалпына келтіріңіз: осы кезеңдегі құжаттар кезегін, автоматтандырулардың іске қосуларын немесе шығынды оқыңыз.

## Әрі қарай

* [Қателер мен шектеулер](https://docs.tungo.kz/kk/platform/errors-and-limits.md): сұрау өтпегенде API не деп жауап береді.
* [Автоматтандыру деген не](https://docs.tungo.kz/kk/automations/overview.md): іске қосулары туралы `automation.*` оқиғалары хабарлайтын сценарийлер.
* [Платформа балансы және шығын](https://docs.tungo.kz/kk/platform/balance.md): баланстың азайғаны туралы оқиғалар және оларға қалай әрекет ету керек.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.