# Вебхуки в Krokul: події CRM у вашу систему

Krokul надсилає події — нова угода, зміна етапу, оплата — POST-запитом на вашу адресу з підписом HMAC.

Теги: вебхуки, webhook, події crm, інтеграція, api, hmac

## Коротко
- **Підписка** — адреса приймача плюс перелік подій, які на неї надсилаються.
- **Доставка** — один запит події на адресу: стан, кількість спроб, причина невдачі.

## Як зробити
### Створити підписку
Krokul почне надсилати вибрані події на вашу адресу.
1. Натисніть «Додати підписку».
2. Впишіть адресу приймача — вона починається з `https://`.
3. Задайте секрет, яким Krokul підписуватиме запити.
4. Позначте потрібні події — під кожною є її опис.
5. Переконайтесь, що ввімкнено «Підписка активна», і натисніть «Записати».
> Порада: Секрет задається один раз і назовні не повертається. Щоб змінити — впишіть новий; порожнє поле лишає старий.
> Важливо: Адресу в локальній чи приватній мережі Krokul не прийме. Активних підписок у компанії — не більше 50.

### Зупинити надсилання
Тимчасово, без видалення підписки.
1. У рядку підписки відкрийте «Дії підписки» й оберіть «Редагувати».
2. Вимкніть «Підписка активна» і натисніть «Записати».
> Порада: У таблиці підписка матиме позначку „Вимкнена“. Події й секрет при цьому не стираються.

### Зʼясувати, чому не дійшло
Журнал доставок показує кожен запит і причину невдачі.
1. Над журналом доставок оберіть потрібну підписку у фільтрі «Підписка».
2. У фільтрі «Стан» оберіть «Не дійшло».
3. Подивіться кількість спроб і текст помилки під рядком доставки.
4. Виправте приймач.
5. У рядку доставки відкрийте «Дії доставки» й оберіть «Надіслати ще раз».
> Порада: Зʼявиться „Доставку поставлено в чергу ще раз“. Доставку, яка зараз надсилається, повторити не можна — дочекайтесь її кінця.

### Видалити підписку
Нові події на цю адресу не поїдуть.
1. У рядку підписки відкрийте «Дії підписки» й оберіть «Видалити».
2. Підтвердьте кнопкою «Видалити».
> Порада: Підписка потрапить у «Кошик» — звідти її можна повернути.

## Як це влаштовано
**Події.** Перелік береться з коду продукту: події, якої немає в переліку, не буде.
- `card.created` — створено угоду;
- `card.statusChanged` — угода перейшла на інший етап;
- `card.won` / `card.lost` — угоду виграно / програно;
- `clientCompany.created` — створено контрагента;
- `contact.created` — створено контакт; `contact.merged` — два контакти злито;
- `document.created` — створено документ (КП, рахунок, акт, договір);
- `invoice.paid` — рахунок оплачено повністю;
- `payment.received` — оплата стала фактом;
- `task.created` — створено задачу.

**Формат запиту.** Метод POST, тіло — JSON з даними події. Із секретом запит несе заголовки `x-crm-timestamp` і `x-crm-signature: sha256=…` — HMAC-SHA256 від мітки часу, крапки й тіла, порахований вашим секретом. Без секрета запит іде без підпису.

**Повтори.** Якщо приймач не відповів успіхом, Krokul повторює через 1 хв, 5 хв, 30 хв, 2 год і далі кожні 6 год — до 8 спроб. Після цього доставка має стан „Не дійшло“.

**Автоматичне вимкнення.** Приймач відповів `410 Gone` — підписку вимкнено одразу. Відкликали ключ API, яким підписку створили (наприклад, Zapier), — вимикаються рівно його підписки.

**Стани доставки:** „У черзі“, „Надсилаємо“, „Доставлено“, „Не дійшло“.

**Журнал.** Показує 100 найновіших доставок: подію, адресу, спроби, час і причину невдачі. Тіла події там немає — у ньому персональні дані клієнтів.

**Застарілі події.** Якщо підписка містить подію, якої в продукті більше немає, у її рядку зʼявиться „1 подія не настане“.

**Хто що може.** Підписки й журнал бачать адміністратор і менеджер. Створювати, змінювати, видаляти й перевідправляти — лише адміністратор.

Повʼязані вікна: «Маркетплейс», «Кошик», «Налаштування».

## Питання й відповіді
### Як отримувати в свою систему нові угоди з Krokul?
Створіть підписку з адресою вашого приймача й подією `card.created`. Krokul надсилатиме POST-запит на кожну нову угоду.

### Як перевірити, що вебхук справді надіслав Krokul?
Задайте секрет у підписці й перевіряйте заголовок `x-crm-signature`: це HMAC-SHA256 від `x-crm-timestamp`, крапки й тіла запиту, порахований вашим секретом. Сам секрет у запиті не передається.

### Чому підписка раптом вимкнулась?
Приймач відповів `410 Gone`, або відкликали ключ API, яким цю підписку створила зовнішня система. Виправте причину й увімкніть «Підписка активна».

### Чи можна подивитися тіло вебхука?
Ні. Журнал показує подію, адресу, стан, спроби й причину невдачі — без тіла, бо в ньому персональні дані клієнтів.

### Звідки керувати ключами API для зворотного напрямку?
Коли зовнішня система сама ходить у Krokul, їй потрібен ключ API — його створюють у «Маркетплейсі».

## Поля й елементи

### Екран «Вебхуки»

| Колонка | Що це й на що впливає |
|---|---|
| Адреса (підписки) | Krokul надсилає на неї запити POST. |
| Події | Порожньо — усі події; червоне «… не настане» — події вже немає в Krokul. |
| Підпис | «Секрет заданий» — запити підписано HMAC; самого секрету екран не показує. |
| Стан | Невдалий запит повторюється з паузою від хвилини до шести годин; після восьмої невдачі — «Не дійшло». |
| Коли | Час останньої зміни стану: черга, спроба чи успіх. |

| Кнопка | Що це й на що впливає |
|---|---|
| Додати підписку | Лише адміністратор; менеджер реєстр бачить, але не змінює. |
| Дії підписки | «Видалити» кладе підписку в кошик; нові події на адресу більше не йдуть. |
| Надіслати ще раз | Повертає доставку в чергу з нульовим лічильником; недоступно, поки вона в черзі чи надсилається. |

| Розділ | Що це й на що впливає |
|---|---|
| Реєстр підписок | Рядок — одна адреса приймача; вимкнена підписка приглушена. |
| Журнал доставок | Кожен запит до приймача; тіла події немає — у ньому можуть бути персональні дані. |
| Причина невдачі | Текст останньої помилки; на відповідь 410 підписку вимикають одразу. |

### Поля форми «Нова підписка»

| Поле | Що це й на що впливає |
|---|---|
| Адреса приймача | Обовʼязкова; запити POST; адреси внутрішньої мережі відхиляються. |
| Секрет | Підпис HMAC-SHA256 у заголовку x-crm-signature; без секрету — без підпису. Назад не показується. |
| Події | Не обрано жодної — усі події. |
| Підписка активна | Вимкнена лишається в реєстрі, але подій не отримує. |

---

Застосунок: https://app.krokul.com/ · API: https://app.krokul.com/api/v1/docs