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

# Вебхуки

> Получайте события Zenedu на свой сервер в реальном времени

Вебхук — это HTTP-запрос, который Zenedu отправляет на ваш адрес, когда в аккаунте происходит определённое действие: оформлен заказ, подписчик получил тег, ответил на тест или написал боту. Вашей системе не нужно опрашивать API, чтобы узнать об изменениях: событие приходит само, обычно в течение нескольких секунд.

## Как получать вебхуки

В Zenedu два способа отправить вебхук. Оба приходят в одном формате, подписываются одинаково и повторяются по одним правилам.

| Способ | Где настроить | Когда отправляется |
| - | - | - |
| Подписка на события | **Настройки → Проект → API и вебхуки** или [Создать вебхук](https://api.zenedu.io/ru/api-reference/webhooks/create.md) | При любом из выбранных [событий](https://api.zenedu.io/ru/webhooks/events.md) во всех ботах аккаунта |
| Действие «Отправить вебхук» | **Маркетинг → Автоматизации** или [Создать автоматизацию](https://api.zenedu.io/ru/api-reference/automations/create.md) | Когда срабатывает автоматизация: только для её триггера и условий, например конкретного тарифа, продукта, тега или ответа |

## Быстрый старт

**1. Создайте обработчик**

Добавьте на свой сервер публичный HTTPS-адрес, который принимает `POST`-запросы с JSON-телом и отвечает статусом `2xx`.

**2. Добавьте вебхук**

Откройте **Настройки → Проект → API и вебхуки**, в блоке **Вебхуки** нажмите **Добавить**, укажите адрес и выберите события. То же самое делает [Создать вебхук](https://api.zenedu.io/ru/api-reference/webhooks/create.md).

**3. Отправьте тест**

Нажмите **Отправить тест** или вызовите [Отправить тестовый вебхук](https://api.zenedu.io/ru/api-reference/webhooks/test.md). На адрес придёт событие [`webhook.test`](https://api.zenedu.io/ru/api-reference/webhook-events/webhook-test).

**4. Проверяйте подпись**

Прежде чем доверять запросу, [проверьте подпись](#подпись) в заголовке `Signature`.

## Формат запроса

Каждый вебхук — это `POST`-запрос с телом в JSON. Тело всегда одной формы: служебные поля и объект события в `data`.

```json theme={null}
{
  "_id": "01JCQ8Z5W3K7X2M4N6P8R0T2V4",
  "event": "tag.added",
  "description": "CRM",
  "timestamp": "2026-11-13T10:24:31+00:00",
  "data": {
    "botId": 42,
    "tag_id": 7,
    "tag_name": "VIP",
    "id": 1503,
    "user_id": 123456789,
    "first_name": "Анна",
    "last_name": "Коваль",
    "username": "anna_k",
    "phone": null,
    "email": "anna@example.com",
    "notes": null,
    "tags": "VIP, Студент",
    "is_active": true,
    "is_blocked": false,
    "last_active_at": "2026-11-13T10:24:29+00:00",
    "created_at": "2026-10-02T08:15:00+00:00",
    "utm_tags": {"utm_source": "instagram"},
    "custom_fields": {"Город": "Киев"}
  }
}
```

| Поле | Описание |
| - | - |
| `_id` | Уникальный ID доставки. Повторные попытки той же доставки приходят с тем же `_id` |
| `event` | Тип события, например `order.paid`. Список — в [каталоге событий](https://api.zenedu.io/ru/webhooks/events.md) |
| `description` | Описание вебхука, которое вы указали при создании, или `null` |
| `timestamp` | Время события в формате ISO 8601 |
| `data` | Объект события. В нём всегда есть `botId` — ID бота, в котором произошло событие. Остальные поля зависят от `event` |

Объекты в `data` совпадают с объектами API: подписчик — как в [Получить подписчика](https://api.zenedu.io/ru/api-reference/subscribers/get.md), заказ — как в [Получить заказ](https://api.zenedu.io/ru/api-reference/orders/get.md). Поля события, например `tag_id` и `tag_name`, лежат рядом с полями подписчика.

### Заголовки

| Заголовок | Описание |
| - | - |
| `Content-Type` | Всегда `application/json` |
| `Signature` | Подпись тела запроса, см. [Подпись](#подпись) |
| `X-Event-Type` | Тип события, то же значение, что в `event` |
| `X-Webhook-ID` | ID доставки, то же значение, что в `_id` |

### Подпись

Zenedu подписывает каждый вебхук. Заголовок `Signature` содержит HMAC-SHA256 от сырого тела запроса в шестнадцатеричном виде, ключ — [API-токен](https://api.zenedu.io/ru/authentication.md#где-взять-токен) аккаунта. Чтобы проверить запрос, вычислите HMAC от тела в том виде, в каком оно пришло, до разбора JSON, и сравните с заголовком:

```php theme={null}
$expected = hash_hmac('sha256', $rawBody, $apiToken);

if (! hash_equals($expected, $signatureHeader)) {
    // запрос отправил не Zenedu
}
```

После сброса API-токена вебхуки подписываются новым токеном.

## Рекомендации

* **Отвечайте быстро.** Верните `2xx` в течение 3 секунд, а тяжёлую работу — запись в CRM, письма, запросы к API — выполняйте в фоновой очереди. Запрос, на который нет ответа за 3 секунды, считается неудачным и будет отправлен повторно.
* **Убирайте дубли.** Одно событие может прийти больше одного раза. Сохраняйте `_id` обработанных доставок и пропускайте повторы.
* **Не полагайтесь на порядок.** Каждый вебхук — отдельный HTTP-запрос, и из-за сетевых задержек или повторной попытки события, произошедшие почти одновременно, могут прийти в другом порядке. Если порядок важен, сравнивайте `timestamp`.
* **Подписывайтесь только на нужные события.** Лишние события нагружают ваш сервер и не дают пользы.

## Что дальше

> [card] [Доставка и повторы](https://api.zenedu.io/ru/webhooks/delivery.md)
>
> Расписание повторных попыток и автоотключение

> [card] [Каталог событий](https://api.zenedu.io/ru/webhooks/events.md)
>
> Все события и их данные

> [card] [Вебхуки в API](https://api.zenedu.io/ru/api-reference/webhooks/list.md)
>
> Управление подписками через API


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.