Repository Webhook Registry — Aries-Serpent/codex¶
Last Updated: 2026-07-11 Version: v0.2.0
**Audit date:2026-07-13
Audited by: Copilot agent W-123 (@agent-infra list-webhooks)
Apply attempted: 2026-03-05T07:02:00Z
Apply attempted by: Copilot agent W-124 (@agent-infra apply-webhooks — dry-run in sandbox)
Method: GET /repos/Aries-Serpent/_codex_/hooks + static codebase analysis
Reference: GitHub Webhooks Guide |
GitHub REST API: Webhooks
Apply Status (W-124 / W-130)¶
| Condition | Status |
|---|---|
CODEX_MASTER_KEY available in workflow |
(via secrets.CODEX_MASTER_KEY) |
WEBHOOK_SECRET available in workflow |
(via secrets.WEBHOOK_SECRET) |
WEBHOOK_RECEIVER_URL repo variable set |
Auto-set by Codespace post-start.sh — format: https://${CODESPACE_NAME}-8765.preview.app.github.dev/webhook/github |
POST /webhook/github endpoint |
Implemented in cognitive_app/src/server/cli_api_server.py |
| Port 8765 public visibility | Must be set manually in Codespace Ports panel for GitHub delivery |
Hooks active: true |
Both hooks have active: false (intentional — activate after confirming delivery works) |
| Apply result | READY — once port 8765 is public and hooks are set to active: true |
To activate: Set port 8765 to public in the Codespace Ports panel. Update both hooks to
active: truein.codex/webhook_config.json, then comment@agent-infra apply-webhookson a PR.WEBHOOK_RECEIVER_URLis now auto-updated on every Codespace start/resume.
Dry-run output (W-124)¶
Creating webhook 'cognitive-brain-ci-feedback' ...
DRY-RUN CREATE webhook https://api.your-cognitive-brain-server.com/webhook/github
events=[push, pull_request, issue_comment, pull_request_review_comment,
workflow_run, repository_dispatch, check_run, check_suite]
Creating webhook 'runner-health-notification' ...
DRY-RUN CREATE webhook https://api.your-cognitive-brain-server.com/webhook/github
events=[workflow_run]
Audit Summary¶
| Item | Value |
|---|---|
| Live webhooks registered | 0 |
| Planned / desired hooks | 2 (see §3) |
| API endpoint | GET /repos/Aries-Serpent/_codex_/hooks |
| API result | 403 via GITHUB_TOKEN (expected — scoped token lacks admin:repo_hook) |
| Confirmed via | Static analysis + absence of .codex/webhook_registry.json entries |
| Tooling | scripts/ci/webhook_configurator.py |
| Declarative config | .codex/webhook_config.json |
| Apply command | @agent-infra apply-webhooks or python scripts/ci/webhook_configurator.py --apply .codex/webhook_config.json |
Why 403? The coding-agent sandbox only has
GITHUB_TOKENwhich does not carryadmin:repo_hookscope. To list or manage hooks you needCODEX_ADMIN_KEY(fine-grained PAT with Webhooks: write) orCODEX_MASTER_KEY(classic PAT withadmin:repo_hook). Run@agent-infra list-webhookson a PR comment to invoke the workflow with the correct secret.
Architecture¶
%%{init: {'accessibility': {'title': 'Diagram showing "GitHub Platform", "Aries-Serpent/_codex_"'}}%%
graph TB
subgraph GitHub["GitHub Platform"]
REPO["Aries-Serpent/_codex_"]
HOOKS["Repository Webhooks\n(Settings Hooks)\n— 0 registered —"]
EVENTS["Event Sources\n(push / PR / issue_comment\n/ workflow_run / etc.)"]
end
subgraph CognitiveBrain["Cognitive Brain (target)"]
CB_API["Cognitive Brain API Server\nhttps://api.your-cognitive-brain-server.com\n NOT YET DEPLOYED"]
CB_MEM["Memory Layer\n(CI feedback ingestion)"]
CB_RUN["Runner Profile Manager\n(COPILOT_RUNNER_PROFILE\nauto-adjustment)"]
end
subgraph Tooling["Webhook Management Tooling"]
WC["scripts/ci/webhook_configurator.py"]
WCF[".codex/webhook_config.json\n(desired state)"]
WCR[".codex/webhook_registry.json\n(live state / hook IDs)"]
AIM[".github/workflows/\nagent_infrastructure_manager.yml\n@agent-infra apply/list-webhooks"]
end
EVENTS -->|POST payload| HOOKS
HOOKS -.pending deployment.-> CB_API
CB_API --> CB_MEM & CB_RUN
WCF -->|apply| WC
WC -->|GitHub REST API| HOOKS
WC -->|writes| WCR
AIM -->|invokes| WC
style CB_API fill:#ef4444,color:#fff
style HOOKS fill:#f59e0b,color:#000
style WC fill:#10b981,color:#fff
Live Hook Inventory (as of 2026-03-05)¶
Result: No hooks registered.
| # | Hook ID | Name | URL | Events | Active | SSL | Created |
|---|---|---|---|---|---|---|---|
| — | — | — | none | — | — | — | — |
The table above will be populated after the first @agent-infra apply-webhooks run.
Planned Hooks (Desired State)¶
Defined in .codex/webhook_config.json. Will be created by
python scripts/ci/webhook_configurator.py --apply .codex/webhook_config.json
once the Cognitive Brain API server is deployed.
Hook 1: cognitive-brain-ci-feedback¶
%%{init: {'accessibility': {'title': 'Sequence Diagram: >>CB: ack
CB'}}%%
sequenceDiagram
participant GH as GitHub
participant WH as Webhook (Hook 1)
participant CB as Cognitive Brain API
participant MEM as Memory Layer
GH->>WH: POST payload (workflow_run completed)
WH->>CB: POST https://api.your-cognitive-brain-server.com/webhook/github
Note over WH,CB: HMAC-SHA256 signature in X-Hub-Signature-256 header
CB->>CB: verify HMAC(WEBHOOK_SECRET)
CB->>MEM: store CI outcome
MEM-->>CB: ack
CB-->>WH: HTTP 200
| Field | Value |
|---|---|
| Name | cognitive-brain-ci-feedback |
| URL | https://api.your-cognitive-brain-server.com/webhook/github (placeholder) |
| Events | push, pull_request, issue_comment, pull_request_review_comment, workflow_run, repository_dispatch, check_run, check_suite |
| Content type | application/json |
| Secret | WEBHOOK_SECRET org secret (HMAC-SHA256) |
| SSL verification | Enabled |
| Active | false — pending server deployment |
| Status | PENDING DEPLOYMENT |
Hook 2: runner-health-notification¶
Shares the same endpoint as Hook 1. Provides the AAIS autonomous runner-selection
feedback loop: after copilot-setup-steps completes, the Cognitive Brain receives
the runner_adequate output and can auto-adjust COPILOT_RUNNER_PROFILE for the
next session.
| Field | Value |
|---|---|
| Name | runner-health-notification |
| URL | https://api.your-cognitive-brain-server.com/webhook/github (shared with Hook 1) |
| Events | workflow_run only |
| Status | PENDING DEPLOYMENT — activate alongside Hook 1 |
Event-to-Workflow Trigger Map¶
These are internal GitHub event triggers (not external webhooks) but are listed here for completeness — they are the upstream source of the POST payloads that external webhooks would relay.
%%{init: {'accessibility': {'title': 'Flowchart showing "workflow_run\n(copilot-setup-steps,\ncognitive_brain_ci_feedback)", "pull_request\n(opened, sync, close)"'}}%%
graph LR
subgraph "External Webhook Events (outbound POST to receiver)"
WR["workflow_run\n(copilot-setup-steps,\ncognitive_brain_ci_feedback)"]
PR["pull_request\n(opened, sync, close)"]
IC["issue_comment\n(@copilot, @agent-infra)"]
PS["push\n(branch push CI)"]
CR["check_run / check_suite\n(status checks)"]
end
subgraph "Critical Internal Listeners (workflows)"
WL1["chatops_copilot_trigger.yml"]
WL2["agent-auth-delegation.yml"]
WL3["cognitive_brain_ci_feedback.yml"]
WL4["agent-handoff-gate.yml"]
WL5["session-watchdog.yml"]
WL6["agent-var-writer.yml"]
end
IC --> WL1 & WL4 & WL5 & WL6
PR --> WL2
WR --> WL3
| GitHub Event | Webhook-Triggerable | Critical Workflows | AAIS Relevance |
|---|---|---|---|
workflow_run |
cognitive_brain_ci_feedback.yml |
Pillar 2: Adaptive Learning | |
pull_request |
agent-auth-delegation.yml |
Pillar 3: Reliability | |
issue_comment |
chatops_copilot_trigger.yml, agent-handoff-gate.yml, session-watchdog.yml, agent-var-writer.yml |
Pillar 3: Automation Coverage | |
push |
20+ workflows | Pillar 1: CI/CD Maturity | |
check_run / check_suite |
Status monitoring | Pillar 3: Observability | |
repository_dispatch |
agent_infrastructure_manager.yml |
Pillar 3: Automation | |
schedule |
(cron, not webhook) | 15+ workflows | — |
workflow_dispatch |
(manual, not webhook) | 60+ workflows | — |
Security¶
%%{init: {'accessibility': {'title': 'Flowchart showing "GitHub\n(sender)", "Receiver endpoint"'}}%%
graph LR
GH["GitHub\n(sender)"] -->|POST + X-Hub-Signature-256| RECV["Receiver endpoint"]
RECV -->|HMAC-SHA256(body, WEBHOOK_SECRET)| VERIFY{"Signature\nvalid?"}
VERIFY -->| Yes| PROCESS["Process payload"]
VERIFY -->| No| REJECT["HTTP 403\nDrop payload"]
style VERIFY fill:#f59e0b,color:#000
style REJECT fill:#ef4444,color:#fff
style PROCESS fill:#10b981,color:#fff
| Security Control | Status | Implementation |
|---|---|---|
| HMAC-SHA256 signature | Configured in schema | WEBHOOK_SECRET org secret webhook_configurator.py |
| SSL/TLS verification | insecure_ssl: "0" |
Set in create_hook() body |
| Secret rotation runbook | Exists | docs/ops/HMAC_rotation.md |
| Token for management | Documented | CODEX_ADMIN_KEY (Webhooks:write) or CODEX_MASTER_KEY (admin:repo_hook) |
| Receiver HMAC validation | Implemented | POST /webhook/github in cognitive_app/src/server/cli_api_server.py — fails closed if WEBHOOK_SECRET not set |
Tooling Reference¶
List live hooks (requires CODEX_ADMIN_KEY)¶
# Via ChatOps comment on any PR:
@agent-infra list-webhooks
# Directly (needs CODEX_ADMIN_KEY env var set):
python scripts/ci/webhook_configurator.py --list
Apply desired-state config (idempotent)¶
# Via ChatOps comment on any PR (uses WEBHOOK_RECEIVER_URL repo variable automatically):
@agent-infra apply-webhooks
# Directly with WEBHOOK_RECEIVER_URL override:
export CODEX_ADMIN_KEY=<PAT with Webhooks:write>
export WEBHOOK_RECEIVER_URL=https://REAL-SERVER-URL/webhook/github
python scripts/ci/webhook_configurator.py --apply .codex/webhook_config.json
# Dry-run first (safe — no API writes):
export WEBHOOK_RECEIVER_URL=https://REAL-SERVER-URL/webhook/github
python scripts/ci/webhook_configurator.py --apply .codex/webhook_config.json --dry-run
WEBHOOK_RECEIVER_URLoverride: If this environment variable is set, it replaces the placeholder URLhttps://api.your-cognitive-brain-server.com/webhook/githubin all webhook config entries. Set this as a GitHub repo variable (Settings Variables Repository variables) so@agent-infra apply-webhookspicks it up automatically without editing.codex/webhook_config.json.
Delete a hook¶
Interactive Codespace Sessions (Auto-URL)¶
For interactive Codespace sessions, the webhook receiver URL is automatically set on every Codespace start/resume:
| Property | Value |
|---|---|
| URL format | https://${CODESPACE_NAME}-8765.preview.app.github.dev/webhook/github |
| Set by | .devcontainer/scripts/post-start.sh |
| Repo variable | WEBHOOK_RECEIVER_URL (auto-updated via gh variable set) |
| Token required | CODEX_MASTER_KEY Codespace secret — required for gh variable set (Actions Variables API). GITHUB_TOKEN cannot access the Variables API and will always return 403. |
| Port visibility | Port 8765 must be org visibility (not public) for GitHub to deliver webhooks while preventing unauthenticated internet access |
| Receiver endpoint | POST /webhook/github in cognitive_app/src/server/cli_api_server.py |
Requirements¶
- Port 8765 must be set to org visibility in the Codespace Ports panel (not public — org restricts access to GitHub organization members only)
WEBHOOK_SECRETmust be set as a Codespace secret (matches the HMAC key on the webhook)CODEX_MASTER_KEYmust be set as a Codespace secret (needed to update the repo variable)
Limitations¶
- The URL changes every time a new Codespace is created (Codespace name is unique)
- Webhooks only work while the Codespace is running and the server is healthy
- Port visibility resets on Codespace rebuild — must be re-set to public
Activation Checklist¶
[ ] For Codespace: Start/resume Codespace post-start.sh auto-sets WEBHOOK_RECEIVER_URL
[ ] Ensure port 8765 is public in Codespace (Ports panel right-click Port Visibility Public)
OR
[ ] For non-Codespace: gh variable set WEBHOOK_RECEIVER_URL --body "https://your-host/webhook/github" --repo Aries-Serpent/_codex_
[ ] Ensure WEBHOOK_SECRET org secret is set (same value as HMAC key on server)
[ ] Run dry-run to confirm URLs:
export WEBHOOK_RECEIVER_URL=https://REAL-SERVER-URL/webhook/github
python scripts/ci/webhook_configurator.py --apply .codex/webhook_config.json --dry-run
[ ] Update .codex/webhook_config.json: set "active": true on both hooks
[ ] Apply (creates hooks with active=true):
@agent-infra apply-webhooks
[ ] Verify at: https://github.com/Aries-Serpent/_codex_/settings/hooks
Both hooks show green checkmark on first delivery
[ ] Run list to confirm hook IDs written to .codex/webhook_registry.json:
@agent-infra list-webhooks
[ ] Update this registry file with live hook IDs and creation timestamps
[ ] Update docs/accountability/.codex/archive/reports/AGENT_ACCOUNTABILITY_REPORT.md
[ ] Update CHANGELOG.md
Related Documents¶
docs/plans/webhook-identification.md— Task definition and event-trigger inventory.codex/webhook_config.json— Desired-state declarative config.codex/webhook_registry.json— Live hook IDs (populated after apply).codex/docs/ADMIN_MANUAL_SETUP_GUIDE.md §5— Manual setup stepsscripts/ci/webhook_configurator.py— CRUD implementation.github/workflows/agent_infrastructure_manager.yml— ChatOps interfacedocs/ops/HMAC_rotation.md— Secret rotation runbookdocs/plans/larger-runners-upgrade.md §5b— Runner-health notification hook plan