Вебхуки

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

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

Тонкий payload

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

{
  "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 и другие — вынесены в отдельный гайд События документов.

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

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

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

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

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

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 и набором событий, переключите проверку подписи на новый секрет, затем удалите старый эндпоинт.

Отладка

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

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

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

Обзор

Endpoints

Подписка

Тонкий payload

Типы событий

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

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

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

Отладка

​Подписка

​Тонкий payload

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

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

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

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

​Отладка

Подписка

Тонкий payload

Типы событий

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

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

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

Отладка