---
kind: task
slug: forge-webhook-receiver
title: Forge webhook receiver — PR and CI events
plan_slug: automation-foundation
epic_slug: forge-webhooks
status: ready
priority: P2
tenant_id: global
owner: unassigned
cursor_todo_id: null
updated_at: "2026-08-03"
---

# Task summary

`POST /api/webhooks/forge/:repoLinkId` with HMAC signature verification; map forge events to `transition_convoy_status(actor: automation)`.

## Description

Core Epic 8 scope. Link PRs to convoys via branch naming convention (`convoy/<slug>/brief-N`) or PR body marker (`echodo-convoy: <uuid>`).

### Events (minimum)

| Forge event | Convoy transition |
|-------------|-------------------|
| PR opened | Ensure convoy in `pr_review` (if Gate 2 not yet human-approved, notify only) |
| PR merged | `pr_review` → `merged` when Gate 2 already approved |
| CI completed (failure) | Optional `blocked` or `convoy_events` notify |

### Security

- Per-repo webhook secret in `repo_links` metadata (reference env var name, not value)
- Zod-validated payload per `forge_type`

## Dependencies

- Epic 3, 4, 7

## Subtasks

- [ ] Route handler + signature verification
- [ ] GitHub + Forgejo payload parsers
- [ ] Convoy lookup by branch/body marker
- [ ] Register webhook URL helper on connect (optional UX)

## Estimation

M

## Acceptance criteria

- [ ] Merge webhook moves convoy from `pr_review` to `merged` when Gate 2 approved
- [ ] Invalid signature returns 401
- [ ] Unknown branch logs and returns 200 (no retry storm)

## Links

- Epic: `./Epic-forge-webhooks.md`