Реагировать на приём и увольнение

Вместо периодического опроса подпишитесь на события и обновляйте свою копию, как только сотрудника завели или уволили в ТОО «Керуен». Событие лишь сообщает, что именно изменилось, — актуальные данные вы забираете своим ключом.

Подписками управляет область webhooks:manage, а перечитывание карточек требует employees:read.

Подпишитесь на события

Заведите endpoint на приём и удаление сотрудников. secret в ответе показывается один раз — сохраните его в менеджере секретов, им проверяется подпись каждой доставки.

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://keruen.example/hooks/doodocs",
    "event_types": ["employee.changed", "employee.deleted"]
  }'

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

Проверьте подпись

Каждая доставка несёт заголовок Doodocs-Signature: t=<unix>,v1=<hex>, где 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)

Перечитайте и примените upsert

В payload приходит только employee_id. Забирайте карточку своим ключом — так к данным применяются область ключа и редакция полей, а персональные данные не уезжают на внешний URL.

curl -H "X-API-Key: ddp_ВАШ_КЛЮЧ" \
  "https://app.doodocs.kz/api/developer/v1/employees/3f2a9c7e-…?expand=person&expand=department"

employee.changed → перечитайте GET /employees/{employee_id} и сделайте upsert по id.
employee.deleted → перечитывание вернёт 404 EMPLOYEE_NOT_FOUND. Не считайте это ошибкой: событие самодостаточно, пометьте сотрудника удалённым.

Обработчик

Дедуплицируйте по id события (доставка «хотя бы один раз»), ответьте 2xx быстро, а тяжёлую работу выносите в фон.

import json, requests

BASE = "https://app.doodocs.kz/api/developer/v1"
HEADERS = {"X-API-Key": "ddp_ВАШ_КЛЮЧ"}
SECRET = "…"                                   # сохранённый secret подписки

def handle(headers, body: bytes):
    if not verify(SECRET, headers["Doodocs-Signature"], body):
        return 401
    event = json.loads(body)
    if seen(event["id"]):                     # дедупликация по id события
        return 200

    employee_id = event["data"]["employee_id"]
    if event["type"] == "employee.deleted":
        mark_deleted(employee_id)
        return 200

    resp = requests.get(f"{BASE}/employees/{employee_id}", headers=HEADERS,
                        params={"expand": ["person", "department"]})
    if resp.status_code == 404:               # гонка: удалён между событием и перечитом
        mark_deleted(employee_id)
    else:
        upsert(resp.json())                   # employee.changed = create + update
    return 200

Между employee.changed и вашим перечитом сотрудника могут удалить — тогда GET /employees/{id} вернёт 404. Трактуйте это как удаление, а не как сбой.

Дальше

Синхронизировать всех сотрудников

Первичная выгрузка и полный перечит для сверки удалений.

Вебхуки

Все типы событий, надёжность доставки и отладка.

Начало работы

Сотрудники

Документы

Рецепты

Реагировать на приём и увольнение

Обработчик

Дальше

Синхронизировать всех сотрудников

Вебхуки

​Обработчик

​Дальше

Синхронизировать всех сотрудников

Вебхуки

Обработчик

Дальше