---
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-07-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.

## 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.

**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.

## Tasks

_To be decomposed when epic graduates to `ready`._