> ## 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/uk/api-reference/webhooks/create.md) | Під час будь-якої з обраних [подій](https://api.zenedu.io/uk/webhooks/events.md) в усіх ботах акаунта |
| Дія «Надіслати вебхук» | **Маркетинг → Автоматизації** або [Створити автоматизацію](https://api.zenedu.io/uk/api-reference/automations/create.md) | Коли спрацьовує автоматизація: лише для її тригера та умов, наприклад конкретного тарифу, продукту, тегу або відповіді |

## Швидкий старт

**1. Створіть обробник**

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

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

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

**3. Надішліть тест**

Натисніть **Надіслати тест** або викличте [Надіслати тестовий вебхук](https://api.zenedu.io/uk/api-reference/webhooks/test.md). На адресу прийде подія [`webhook.test`](https://api.zenedu.io/uk/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/uk/webhooks/events.md) |
| `description` | Опис вебхука, який ви вказали під час створення, або `null` |
| `timestamp` | Час події у форматі ISO 8601 |
| `data` | Об’єкт події. У ньому завжди є `botId` — ID бота, у якому відбулася подія. Інші поля залежать від `event` |

Об’єкти в `data` збігаються з об’єктами API: підписник — як в [Отримати підписника](https://api.zenedu.io/uk/api-reference/subscribers/get.md), замовлення — як в [Отримати замовлення](https://api.zenedu.io/uk/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/uk/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/uk/webhooks/delivery.md)
>
> Розклад повторних спроб і автовимкнення

> [card] [Каталог подій](https://api.zenedu.io/uk/webhooks/events.md)
>
> Усі події та їхні дані

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


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