wiki/tasks/multi-agent/reports/dev-2026-05-21-webhooks.md

Dev Report: Настройка Webhooks (Plane + Gitea → Orchestrator)

Дата: 2026-05-21 Статус: DONE

Задача

Настроить webhooks из Plane и Gitea в Orchestrator с HMAC-верификацией подписи.

Сделано

• Task 1: Создан webhook в Gitea через API (id=2, events: push/pull_request/status)
• Task 2: Создан webhook в Plane через прямую вставку в PostgreSQL (Plane CE не экспортирует webhook API через /api/v1/)
• Task 3: Добавлена HMAC-SHA256 верификация в оба handler'а (gitea.py, plane.py)
• Task 4: Пересобран Orchestrator, протестирован end-to-end (push → event в БД)
• Task 5: Создана документация docs/SETUP_WEBHOOKS.md

Изменённые файлы

• /home/slin/repos/orchestrator/src/webhooks/gitea.py — добавлена verify_gitea_signature(), HTTPException на 401
• /home/slin/repos/orchestrator/src/webhooks/plane.py — добавлена verify_plane_signature(), HTTPException на 401
• /home/slin/repos/orchestrator/.env — заполнены ORCH_GITEA_WEBHOOK_SECRET и ORCH_PLANE_WEBHOOK_SECRET
• /home/slin/repos/orchestrator/docs/SETUP_WEBHOOKS.md — новый файл, полная документация

Результат

Gitea webhook

• Webhook создан: URL https://openclaw.mva154.duckdns.org/orchestrator/webhook/gitea
• Secret: fc122bd5cba8740c90f1d6bd64f07d3c2593d6ca
• Push в enduro-trails → event записывается в БД (проверено: event id=18, source=gitea, type=push)

Plane webhook

• Webhook создан в БД: id 93f0c342-a614-4248-9d0f-c107276f5620
• URL: https://openclaw.mva154.duckdns.org/orchestrator/webhook/plane
• Secret: e7d95ee9114155d5ee55a95e23ffff7c89d38b16

Signature verification

• Запрос без подписи → 401 ✓
• Запрос с неверной подписью → 401 ✓
• Запрос с правильной подписью → 200 ✓
• Если secret пустой в .env → верификация пропускается (backward compatible)

Проблемы и решения

1. Plane API не поддерживает webhook management через /api/v1/ — решено прямой вставкой в PostgreSQL (пароль: plane)
2. Git push rejected на тестовой ветке — решено через fetch + reset --hard перед тестом
3. Plane webhook signature header — использован X-Plane-Signature (нужно проверить при реальном событии из Plane, может отличаться)

Заметки

• Plane CE (stable) хранит webhooks в таблице webhooks, workspace_id связан через workspaces.slug='ag_proj'
• Gitea отправляет подпись в header X-Gitea-Signature как hex digest (без префикса sha256=)
• Config уже содержал поля gitea_webhook_secret и plane_webhook_secret с env_prefix ORCH_