Вебхуки

Вместо периодического опроса вы можете подписаться на события: когда данные в вашем тенанте меняются, 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`	Изменены идентификационные поля человека: имя, ИИН, личные контакты

Переименование человека приходит только как person.changed — событие employee.changed его не несёт. Чтобы имена оставались свежими, подписывайтесь на оба типа: фильтр updated_since в списках переименования не отражает.

Оба типа несут одинаковый payload {"employee_id": …}. Если у человека несколько карточек сотрудника, person.changed придёт по каждой из них — перечитайте GET /employees/{employee_id} и примените upsert так же, как для employee.changed. События по документам — 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 события: то же значение приходит в заголовке Doodocs-Event-Id, поэтому проверить повтор можно не разбирая тело.

Управление подпиской

Изменить адрес или набор событий

PATCH /webhook_endpoints/{id} меняет url, event_types или и то и другое. Не переданные поля сохраняют текущее значение, пустой список событий тоже означает «не менять». Секрет при этом не меняется. Смена адреса дополнительно обнуляет счётчик неудачных доставок, поэтому починка не наследует отказы мёртвого хоста.

curl -X PATCH -H "X-API-Key: $DOODOCS_API_KEY" -H "Content-Type: application/json" \
  https://app.doodocs.kz/api/developer/v1/webhook_endpoints/wh_3a1c… \
  -d '{ "event_types": ["employee.changed", "person.changed", "employee.deleted"] }'

Ротация секрета

POST /webhook_endpoints/{id}/_rotate_secret выдаёт новый секрет и возвращает его один раз. Прежний секрет продолжает работать заданное время — по умолчанию 24 часа, но окно задаётся полем grace_seconds (максимум неделя). Всё это время каждая доставка несёт две подписи.

Заголовок	Чем подписано
`Doodocs-Signature`	новым секретом
`Doodocs-Signature-Previous`	прежним секретом

curl -X POST -H "X-API-Key: $DOODOCS_API_KEY" -H "Content-Type: application/json" \
  https://app.doodocs.kz/api/developer/v1/webhook_endpoints/wh_3a1c…/_rotate_secret -d '{}'

{
  "endpoint": {
    "id": "wh_3a1c…",
    "previous_secret_expires_at": "2026-02-11T09:30:00Z"
  },
  "secret": "whsec_…"
}

Порядок безопасной ротации: примите оба заголовка на своей стороне → вызовите ротацию → выкатите новый секрет → снова принимайте только Doodocs-Signature. Уложитесь в окно до previous_secret_expires_at: после него старый секрет перестаёт подписываться, и проверка по нему начнёт падать.

Если секрет утёк

Плавная ротация оставляет утёкший секрет рабочим на всё окно — этого времени достаточно, чтобы подделать доставки. Передайте grace_seconds: 0: прежний секрет перестаёт действовать немедленно.

curl -X POST -H "X-API-Key: $DOODOCS_API_KEY" -H "Content-Type: application/json" \
  https://app.doodocs.kz/api/developer/v1/webhook_endpoints/wh_3a1c…/_rotate_secret \
  -d '{ "grace_seconds": 0 }'

Хранится ровно один прежний секрет, поэтому вторая ротация внутри открытого окна отклоняется с кодом DEVELOPER.WEBHOOK_ROTATION_IN_PROGRESS (409). Дождитесь previous_secret_expires_at или выполните немедленную ротацию с grace_seconds: 0.

Повторное включение

POST /webhook_endpoints/{id}/_reenable снимает автоотключение и обнуляет счётчик отказов. То же самое можно сделать в приложении: Настройки → Интеграции → «Для разработчиков» → Вебхуки.

curl -X POST -H "X-API-Key: $DOODOCS_API_KEY" -H "Content-Type: application/json" \
  https://app.doodocs.kz/api/developer/v1/webhook_endpoints/wh_3a1c…/_reenable -d '{}'

События за время простоя не доигрываются автоматически. Пока подписка отключена, события не копятся. Неудачные попытки видны в журнале доставок, и каждую можно отправить заново поштучно. Для массовой сверки используйте опрос: GET /employees?updated_since=<last_success_at> и GET /documents?updated_since=<last_success_at>&order_by=DOCUMENT_ORDER_UPDATED_AT_ASC — момент последней успешной доставки виден в поле last_success_at подписки.

Журнал доставок

GET /webhook_endpoints/{endpoint_id}/deliveries показывает попытки доставки от новых к старым: что отправлено, когда и что ответил ваш сервер. Записи хранятся 30 дней и содержат только идентификаторы и исход, без полезной нагрузки.

curl -H "X-API-Key: $DOODOCS_API_KEY" \
  "https://app.doodocs.kz/api/developer/v1/webhook_endpoints/wh_3a1c…/deliveries?status=WEBHOOK_DELIVERY_STATUS_FAILED&limit=50"

{
  "deliveries": [
    {
      "id": "d9f1…",
      "event_id": "evt_9f2c…",
      "event_type": "document.completed",
      "resource_id": "8c2d5a91-…",
      "attempt": 3,
      "status": "WEBHOOK_DELIVERY_STATUS_FAILED",
      "response_status": 503,
      "error": "http status 503",
      "create_time": "2026-02-10T09:30:00Z"
    }
  ],
  "next_page_token": ""
}

event_id совпадает с заголовком Doodocs-Event-Id и полем id в теле, поэтому запись сопоставляется с вашим собственным логом. Фильтр status принимает WEBHOOK_DELIVERY_STATUS_SUCCEEDED или WEBHOOK_DELIVERY_STATUS_FAILED.

Отправить событие заново

POST /webhook_endpoints/{endpoint_id}/deliveries/{delivery_id}/_redeliver ставит то же событие в очередь ещё раз — так восстанавливают пропущенное за время сбоя.

curl -X POST -H "X-API-Key: $DOODOCS_API_KEY" -H "Content-Type: application/json" \
  https://app.doodocs.kz/api/developer/v1/webhook_endpoints/wh_3a1c…/deliveries/d9f1…/_redeliver -d '{}'

Повтор несёт исходный event_id, поэтому получатель, который дедуплицирует по нему, узнает повтор и не обработает событие дважды. Отключённой подписке повтор отклоняется кодом DEVELOPER.WEBHOOK_DELIVERY_NOT_REDELIVERABLE: сначала включите её.

Отладка

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

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

{ "status_code": 200, "error": "" }

status_code — код, которым ваш сервер ответил на тестовую доставку. Если соединение не удалось, status_code будет 0, а причина окажется в error.

Обзор

Endpoints

Подписка

Тонкий payload

Типы событий

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

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

Управление подпиской

Изменить адрес или набор событий

Ротация секрета

Если секрет утёк

Повторное включение

Журнал доставок

Отправить событие заново

Отладка

​Подписка

​Тонкий payload

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

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

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

​Управление подпиской

​Изменить адрес или набор событий

​Ротация секрета

​Если секрет утёк

​Повторное включение

​Журнал доставок

​Отправить событие заново

​Отладка

Подписка

Тонкий payload

Типы событий

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

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

Управление подпиской

Изменить адрес или набор событий

Ротация секрета

Если секрет утёк

Повторное включение

Журнал доставок

Отправить событие заново

Отладка