---
kind: epic
slug: forge-webhooks
title: Forge webhooks — PR and CI events drive convoy transitions
plan_slug: automation-foundation
status: draft
priority: P2
tenant_id: global
cursor_epic_id: null
updated_at: "2026-08-03"
---

# Epic objective

Webhook receivers on Echodo for connected forges: PR opened → `pr_review`; PR merged → trigger doc-writer job + `merged`; CI failed → optional `blocked` or notify. Supports Forgejo and GitHub adapters minimum.

PR checks recovery UI in mission control when CI fails (Autensa benchmark).

## In scope / out of scope

**In scope**

- `POST /api/webhooks/forge/:repoLinkId` with signature verification.
- Map events to `transition_convoy_status(actor: automation)`.
- Link PR branch to convoy/brief via branch naming convention or PR body marker.
- PR checks recovery panel (classify failures, rerun where API allows).

**Out of scope**

- Replacing Coolify deploy webhooks for Gate 3 prod promote (manual or separate integration).

## Dependencies

- Epic 3, 4, 7.

## Acceptance criteria

- [ ] Merge on Forgejo moves convoy from `pr_review` to `merged` when Gate 2 approved.
- [ ] Mission control shows PR check failures with recovery actions for `pr_review` convoys.

## Tasks

| Task | Link | Status |
|------|------|--------|
| Webhook receiver | [Task-forge-webhook-receiver](./Task-forge-webhook-receiver.md) | ready |
| PR checks recovery panel | [Task-pr-checks-recovery-panel](./Task-pr-checks-recovery-panel.md) | draft |