> ## 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.

# События документов

> Вебхуки document.* и реакция на смену статуса

Вместо опроса статуса подпишитесь на события: когда документ в вашем тенанте
проходит очередной этап, Doodocs People сам отправит `POST` на ваш URL. Подписки
управляются областью `webhooks:manage` — общий механизм разобран на странице
[Вебхуки](/ru/api-reference/webhooks).

```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://keruen.example/hooks/doodocs",
    "event_types": ["document.sent", "document.completed", "document.rejected"]
  }'
```

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

События покрывают весь жизненный цикл — от отправки до завершения или обрыва.

| Тип                         | Когда                                                      |
| --------------------------- | ---------------------------------------------------------- |
| `document.sent`             | Документ отправлен по маршруту (`DRAFT` запущен)           |
| `document.approval_started` | Начался этап согласования (`ON_APPROVAL`)                  |
| `document.signing_started`  | Начался этап подписания (`ON_SIGN`)                        |
| `document.completed`        | Все шаги пройдены, документ подписан (`COMPLETED`)         |
| `document.rejected`         | Документ отклонён участником (`REJECTED`)                  |
| `document.change_requested` | Участник запросил изменения (`CHANGE_REQUESTED`)           |
| `document.revoked`          | Документ отозван инициатором или руководителем (`REVOKED`) |
| `document.deleted`          | Документ удалён — перечитывание вернёт `404`               |

## Тонкий payload

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

```json theme={null}
{
  "id": "evt_7a1b…",
  "type": "document.completed",
  "occurred_at": "2026-02-10T09:30:00Z",
  "data": { "document_id": "8c2d…" }
}
```

Актуальное состояние забирайте обычным запросом своим ключом:

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

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

<Note>
  Проверяйте подпись каждой доставки: заголовок `Doodocs-Signature: t=<unix>,v1=<hex>`,
  где `v1` — это `HMAC-SHA256(secret, "{t}.{тело}")`. Как это сделать и отклонить
  просроченные доставки — на странице [Вебхуки](/ru/api-reference/webhooks).
</Note>

<Warning>
  События документов доставляются по **каждому** документу тенанта — независимо от
  того, какие документы доступны владельцу endpoint по правам. Payload раскрывает
  только идентификатор и время смены статуса, но никогда не содержимое. Само содержимое
  остаётся за правами: перечитывание недоступного документа вернёт `404`
  `DOCUMENT_NOT_FOUND` (см. [Обзор документов](/ru/guides/documents/overview)). Не
  считайте получение события подтверждением доступа к документу.
</Warning>

## Дальше

<Columns cols={2}>
  <Card title="Вебхуки" icon="bell" href="/ru/api-reference/webhooks">
    Подписка, проверка подписи и надёжность доставки.
  </Card>

  <Card title="Обзор документов" icon="file-lines" href="/ru/guides/documents/overview">
    Статусы и структура объекта, который вы перечитываете.
  </Card>
</Columns>