charles/claude-hooks

Fork

You've already forked claude-hooks

Code Issues 10 Pull requests Projects Releases Packages 1 Wiki Activity Actions

MF-3: Per-forge webhook ingress + signature verification #294

New issue

Closed

opened 2026-04-23 23:33:12 +00:00 by code-lead · 0 comments

code-lead commented

2026-04-23 23:33:12 +00:00

Collaborator

Copy link

Acceptance criteria

Routes

Three HTTP routes: /webhooks/forgejo, /webhooks/github, /webhooks/gitlab.
Legacy /webhooks stays as a Forgejo alias — zero-cost, indefinite.
Unknown forge events log + return 204 (no-op), never 500.

Signature verification (per forge)

Forgejo: HMAC-SHA256 of body with webhook_secret, header X-Forgejo-Signature (current behaviour preserved).
GitHub: HMAC-SHA256 with X-Hub-Signature-256: sha256=<hex> (prefix stripped before compare).
GitLab: static token equality check on X-Gitlab-Token header. Documented in code + docs as plaintext (not HMAC); per-forge secrets MUST be unique per repo to limit blast radius.
Failure → 403.

Normaliser

New apps/server/src/http/webhook-normalize.ts with pure functions:
- normalizeGitHubPayload(event, body) → ForgeEvent
- normalizeGitLabPayload(event, body) → ForgeEvent
- normalizeForgejoPayload(event, body) → ForgeEvent (either refactor the existing dispatch or call through the shared shape).
Pure — no I/O, no logging side effects beyond a returned diagnostic shape.

Shared event union

ForgeEvent discriminated union exported from packages/shared covering every event the Forgejo dispatch currently handles: issues.assigned, issues.labeled, issues.closed, pull_request.opened, pull_request.closed, pull_request_review.request, pull_request_review.approved, pull_request_review.changes_requested, issue_comment.created, action_run.* / workflow_run.* (CI status).
Events the service doesn't currently dispatch round-trip through ForgeEvent.Unhandled — still 204, never lost.

Tests

webhook-normalize.test.ts: each forge's real-world payload (captured fixture, trimmed of PII) normalises to the same ForgeEvent for equivalent actions.
Signature-fail scenarios per forge return 403.
Unknown event type returns 204.

Out of scope

Rewriting Forgejo dispatch from switch (event) to the normalised ForgeEvent union in one go. Can be a follow-up once the union is stable; keep today's Forgejo handlers as-is, just call the normaliser for parity.
Replaying missed webhooks after outage — separate reliability concern.

References

Spec: specs/multi-forge.md § MF-3.
apps/server/src/http/webhook.ts — current Forgejo-only entry.
apps/server/src/http/webhook-handlers.ts — event handlers that receive the normalised events.
Forgejo webhook signature doc (existing repo usage).

Dependencies

Blocks on MF-4 (adapter factory) — the handler dispatch reads per-repo forge binding to know which normaliser fits the incoming path.
Independent of adapter internals — operates on HTTP bodies only. Can start as soon as MF-4 lands in parallel with MF-1.

Depends on #295 (MF-4)

As a platform engineer, I want webhook deliveries from Forgejo, GitHub, and GitLab routed into the same domain dispatch pipeline (normalised at the HTTP boundary) so that the rest of the service stays forge-agnostic and signature verification is uniformly enforced. ## Acceptance criteria ### Routes - [ ] Three HTTP routes: `/webhooks/forgejo`, `/webhooks/github`, `/webhooks/gitlab`. - [ ] Legacy `/webhooks` stays as a Forgejo alias — zero-cost, indefinite. - [ ] Unknown forge events log + return `204` (no-op), never `500`. ### Signature verification (per forge) - [ ] **Forgejo**: HMAC-SHA256 of body with `webhook_secret`, header `X-Forgejo-Signature` (current behaviour preserved). - [ ] **GitHub**: HMAC-SHA256 with `X-Hub-Signature-256: sha256=<hex>` (prefix stripped before compare). - [ ] **GitLab**: static token equality check on `X-Gitlab-Token` header. Documented in code + docs as plaintext (not HMAC); per-forge secrets MUST be unique per repo to limit blast radius. - [ ] Failure → `403`. ### Normaliser - [ ] New `apps/server/src/http/webhook-normalize.ts` with pure functions: - `normalizeGitHubPayload(event, body) → ForgeEvent` - `normalizeGitLabPayload(event, body) → ForgeEvent` - `normalizeForgejoPayload(event, body) → ForgeEvent` (either refactor the existing dispatch or call through the shared shape). - [ ] Pure — no I/O, no logging side effects beyond a returned diagnostic shape. ### Shared event union - [ ] `ForgeEvent` discriminated union exported from `packages/shared` covering every event the Forgejo dispatch currently handles: `issues.assigned`, `issues.labeled`, `issues.closed`, `pull_request.opened`, `pull_request.closed`, `pull_request_review.request`, `pull_request_review.approved`, `pull_request_review.changes_requested`, `issue_comment.created`, `action_run.*` / `workflow_run.*` (CI status). - [ ] Events the service doesn't currently dispatch round-trip through `ForgeEvent.Unhandled` — still `204`, never lost. ### Tests - [ ] `webhook-normalize.test.ts`: each forge's real-world payload (captured fixture, trimmed of PII) normalises to the same `ForgeEvent` for equivalent actions. - [ ] Signature-fail scenarios per forge return `403`. - [ ] Unknown event type returns `204`. ## Out of scope - Rewriting Forgejo dispatch from `switch (event)` to the normalised `ForgeEvent` union in one go. Can be a follow-up once the union is stable; keep today's Forgejo handlers as-is, just call the normaliser for parity. - Replaying missed webhooks after outage — separate reliability concern. ## References - Spec: [`specs/multi-forge.md`](../src/branch/main/specs/multi-forge.md) § MF-3. - `apps/server/src/http/webhook.ts` — current Forgejo-only entry. - `apps/server/src/http/webhook-handlers.ts` — event handlers that receive the normalised events. - Forgejo webhook signature doc (existing repo usage). ## Dependencies - **Blocks on MF-4** (adapter factory) — the handler dispatch reads per-repo forge binding to know which normaliser fits the incoming path. - Independent of adapter internals — operates on HTTP bodies only. Can start as soon as MF-4 lands in parallel with MF-1.  - Depends on #295 (MF-4)

code-lead added the

area:security

area:webhook

type:user-story

labels

2026-04-23 23:33:12 +00:00

dev was assigned by code-lead

2026-04-23 23:33:12 +00:00

code-lead was assigned by charles

2026-04-23 23:34:38 +00:00

dev was unassigned by charles

2026-04-23 23:34:38 +00:00

code-lead referenced this issue

2026-04-23 23:34:47 +00:00

Tracking: multi-forge spec breakdown (Forgejo + GitHub + GitLab behind ForgePort) #291

code-lead removed their assignment

2026-04-23 23:35:06 +00:00

dev was assigned by code-lead

2026-04-23 23:35:06 +00:00

code-lead referenced this issue from a commit

2026-04-23 23:49:35 +00:00

feat(webhook): per-forge ingress + signature verification (MF-3)

code-lead referenced this issue from a pull request that will close it,

2026-04-23 23:49:44 +00:00

feat(webhook): per-forge ingress + signature verification (MF-3) #305

dev referenced this issue from a pull request that will close it,

2026-04-23 23:53:22 +00:00

feat(webhook): per-forge webhook ingress + signature verification (MF-3) #307

charles referenced this issue from a commit

2026-04-24 08:50:01 +00:00

feat(webhook): per-forge ingress + signature verification (MF-3)

code-lead closed this issue

2026-04-24 09:11:04 +00:00

No Branch/Tag specified

main

chore/sync-pre-push-from-forge-base

fix/flows-yaml-dispatch-identity

feat/board-tap-to-assign

dev/1107

code-lead/1106

code-lead/1108

dev/1104

code-lead/1103

code-lead/1080

dev/1087

feat/flows-yaml-ci-events

chore/board-drop-stalled-and-density-controls

fix/flows-yaml-routes-always-register

flows-yaml/api-defaults

dev/1023

fix/event-log-history-bleed

fix/janitor-fix-ci-logs-and-cap

dev/1022

fix/board-card-provider

code-lead/1036

dev/1025

code-lead/1020

dev/1017

code-lead/1026

feat/web-shortcut-registry-1018

dev/1015

code-lead/1009

code-lead/1008

dev/975

dev/969

dev/973

dev/967

code-lead/968

code-lead/953

dev/970

dev/976

code-lead/966

code-lead/956

code-lead/951

dev/962

dev/963

dev/977

dev/955

dev/983

dev/961

dev/974

code-lead/950

code-lead/939

dev/941

dev/940

dev/937

dev/938

dev/936

dev/935

feat/web-i18n-fr-locale

feat/spec-editor-ui-polish

chore/drop-legacy-compat

fix/skills-drop-preview-pane

fix/882-skills-safety-rail

dev/911

dev/909

dev/923

dev/917

dev/915

feat/879-sr11-m2-drop-legacy-skill

code-lead/873

dev/881

code-lead/869

dev/867

code-lead/845

code-lead/843

code-lead/844

dev/837

dev/861

dev/849

code-lead/837

code-lead/842

fix/dedup-rebase-inflight

dev/838

code-lead/847

dev/833

code-lead/848

pr/838

code-lead/841

feat/settings-save-bar/836

code-lead/840

dev/846

code-lead/839

dev/832

fix/board-sse-stale-cache

dev/834

dev/835

feat/settings-breadcrumbs

feat/forge-oauth-credentials

refactor/service-config-consolidation

feat/agent-tokens-to-secrets

feat/gitlab-oauth-to-db

feat/authelia-rip-and-voice-fixes

fix/rebase-storm-and-dead-letter

code-lead/797

code-lead/796

dev/811

code-lead/798

dev/810

code-lead/795

dev/808

code-lead/794

dev/805

dev/802

dev/803

feat/avatar-menu-settings-entry

feat/per-agent-token-tracking

dev/793

dev/747

dev/752

code-lead/790

code-lead/759

dev/756

dev/760

dev/741

dev/767

dev/740

dev/709

dev/644

dev/637

boss/614

dev/600

dev/611

dev/585

fix/login-bonus-fixes

boss/544

dev/542

refactor/api-prefix-and-session-gate

dev/489

boss/531

boss/518

dev/499

boss/516

dev/530

dev/517

dev/519

dev/515

dev/522

dev/503

dev/471

boss/329

dev/417

dev/418

dev/402

boss/327

dev/334

dev/332

boss/326

boss/325

dev/331

boss/324

boss/323

boss/322

dev/294

test/s11-task-analytics

dev/262

boss/270

dev/268

foreman/ui-consolidation-spec

dev/234

boss/196

boss/176

boss/164

fix/124-session-persist-bind

boss/52

dev/87

boss/73

dev/77

dev/81

dev/82

boss/79

dev/42

dev/35

boss/7

No results found.

Labels

Clear labels

area:agents

Agent types, pool scheduling, per-instance config

area:dashboard

Dashboard UI and observability surfaces

area:database

DB layer — schema, migrations, ORM, raw SQL

area:design

UI/UX mockup work — routes to designer agent

area:design-review

Design review dispatch — routes to design-reviewer agent

area:flows

Flow runner — YAML loader, executor, op registry, expression eval

area:infra

Deployment, isolation, containers, systemd units

area:meta

Tracking, scaffolding, project setup

area:security

Security — routes to reviewer-security (opus)

area:sessions

Session-id store, Claude SDK resume logic

area:webhook

Forgejo webhook routing and handlers

area:workdir

Clone cache, worktrees, git identity

security

Security-sensitive issue

Tracking or decisions, not implementation work

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

dev

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

charles/claude-hooks#294

Reference in a new issue

Repository

charles/claude-hooks

Title

Body

No description provided.

Delete branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?

Rows
Columns