API, webhooks и разработка модулей

Для чего нужен

• Безопасно читать и изменять данные извне.
• Получать события Taska в реальном времени.
• Создавать частные и публичные продуктовые расширения.

Кто работает

• Администратор выпускает токен.
• Разработчик интегрирует.
• Владелец данных утверждает scopes.
• Партнёр публикует приложение после проверки.

Порядок работы

1. 1

   Определите сценарий

   Сущности, операции, частота и направление данных.

2. 2

   Создайте токен

   Минимальные scopes, срок, понятное имя и IP-ограничение при необходимости.

3. 3

   Используйте контекст

   Tenant определяется доменом или публичным tenant token; организация передаётся безопасным контекстом.

4. 4

   Защитите записи

   Idempotency-Key для повторов, If-Match для конкурентных изменений.

5. 5

   Подпишите webhooks

   Проверяйте secret/signature, timestamp и event id.

6. 6

   Наблюдайте

   Логи доставки, retry, dead-letter queue и аудит.

Возможности

• Scoped tokens.
• REST API.
• Idempotency.
• Optimistic locking.
• Signed webhooks.
• Rate limits.
• Marketplace manifests.
• Tenant isolation.

Связи с другими модулями

• Все модули выставляют разрешённые сущности.
• Domain events питают webhooks.
• Audit фиксирует мутации.
• Marketplace управляет установкой.

Что происходит дальше

• Токен показывается один раз.
• Webhook получает подписанные события.
• Ошибки ретраятся и попадают в DLQ после лимита.

Пример: Форма сайта

Лендинг должен создавать заявки.

1. Администратор создаёт отдельное подключение формы.
2. Получает публичный ключ и endpoint.
3. Маппит поля и воронку.
4. Сайт отправляет idempotent запрос.
5. Taska создаёт заявку с UTM и уведомляет ответственного.

Проверка перед запуском

• Scopes минимальны.
• Секрет не попал в frontend.
• Webhook fail-closed.
• Повторы идемпотентны.
• Tenant и organization scope проверены.
• Технические ошибки преобразуются в понятные сообщения.

Частые вопросы