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

# Вебхуки

> Мгновенные уведомления об изменениях данных

Вместо периодического опроса вы можете подписаться на события: когда данные в
вашем тенанте меняются, Doodocs People сам отправит `POST` на ваш URL.

<Note>
  Область ключа для управления подписками — `webhooks:manage`. Доставка «хотя бы
  один раз»: возможны повторы, дедуплицируйте по полю `id`.
</Note>

## Подписка

```bash theme={null}
curl -X POST -H "X-API-Key: ddp_ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  https://app.doodocs.kz/api/developer/v1/webhook_endpoints \
  -d '{ "url": "https://ваш-сервер/hooks/doodocs", "event_types": ["employee.changed", "employee.deleted"] }'
```

В ответе придёт `secret` подписки — он показывается **один раз**. Сохраните его:
им проверяется подпись каждой доставки.

## Тонкий payload

Событие несёт тип, идентификатор ресурса и время — но не сами данные:

```json theme={null}
{
  "id": "evt_9f2c…",
  "type": "employee.changed",
  "occurred_at": "2026-02-10T09:30:00Z",
  "data": { "employee_id": "b7e4…" }
}
```

Актуальные данные забирайте обычным запросом своим ключом:
`GET /developer/v1/employees/{employee_id}`. Так к ним автоматически применяются
область ключа и редакция полей, а персональные данные не уезжают на внешний URL.

### Типы событий

| Тип                | Когда                                                                                                                        |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `employee.changed` | Карточка сотрудника создана или изменена, **в том числе переименование связанного человека** (изменение имени/ИИН/контактов) |
| `employee.deleted` | Сотрудник удалён — перечитывание вернёт `404`, событие самодостаточно                                                        |
| `person.changed`   | Изменены идентификационные поля человека (имя, ИИН); полезно, если нужны именно они                                          |

Переименование человека приходит как `employee.changed` по каждому затронутому
сотруднику — это основной канал, чтобы держать имена свежими (фильтр
`updated_since` в списках такие изменения не отражает).

События по документам — `document.sent`, `document.completed`, `document.rejected`
и другие — вынесены в отдельный гайд [События документов](/ru/guides/documents/events).

<Note>
  `employee.changed` объединяет создание и изменение: получив его, перечитайте ресурс
  и примените upsert. Отдельного `created` нет намеренно — источник не всегда может
  надёжно отличить первое появление от последующего изменения.
</Note>

## Проверка подписи

Каждая доставка несёт заголовок:

```
Doodocs-Signature: t=1755244200,v1=5257a86…
```

где `v1` — это `HMAC-SHA256(secret, "{t}.{тело запроса}")` в hex. Проверьте на
своей стороне и отклоните запрос, если подпись не сходится или `t` старше пяти
минут (защита от повторов).

```python theme={null}
import hashlib, hmac, time

def verify(secret: str, header: str, body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, v1 = parts["t"], parts["v1"]
    if abs(time.time() - int(t)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)
```

## Доставка и надёжность

* Ответьте `2xx` быстро и обрабатывайте асинхронно. Таймаут — 10 секунд.
* При неуспехе событие доставляется повторно — до **8 попыток** с
  экспоненциально растущей задержкой, суммарно около **суток**.
* После **20 подряд** окончательно проваленных доставок эндпоинт автоматически
  отключается, и новые события на него не отправляются.
* Доставка — «хотя бы один раз»: возможны повторы. Используйте `id` события для
  дедупликации.

## Эксплуатация

* **Повторное включение.** Отключённый эндпоинт (после серии отказов или
  вручную) включается в настройках приложения: Интеграции → Вебхуки. Эндпоинта
  включения в Developer API сейчас нет.
* **События за время простоя не доигрываются.** Пока эндпоинт отключён, события
  не копятся. После включения сделайте сверку опросом:
  `GET /employees?updated_since=<время отключения>`.
* **Ротация секрета.** Секрет выдаётся один раз при создании и не ротируется.
  Чтобы сменить его — создайте новый эндпоинт с тем же URL и набором событий,
  переключите проверку подписи на новый секрет, затем удалите старый эндпоинт.

## Отладка

Отправьте тестовое событие на существующую подписку:

```bash theme={null}
curl -X POST -H "X-API-Key: ddp_ВАШ_КЛЮЧ" \
  https://app.doodocs.kz/api/developer/v1/webhook_endpoints/{id}/_test
```

Ответ содержит код состояния, с которым ваш сервер принял тестовую доставку.