feat(agent_api_keys): one-call webhook-trigger setup endpoint (#329)

danielmillerp · claude · web-flow · commit 9cc71fb998d0 · 2026-06-23T20:34:49.000Z
## What Adds `POST /agent_api_keys/webhook-trigger` — wires a webhook trigger in **one call**: - registers a `github`/`slack` signature-verification key for the agent (auto-generates the signing secret if not provided), - returns the ready-to-paste **forward webhook URL** + the **secret** (shown once). ``` POST /agent_api_keys/webhook-trigger { "agent_name": "golden-agent", "source": "github", "name": "<owner/repo>", "forward_path": "github-pr/<config-id>" } → { key_id, secret, webhook_path, webhook_url } ``` ## Why The pieces to trigger an agent from a webhook already exist (the `/agents/forward` ingress verifies the signature against an agent key, and `POST /agent_api_keys` registers keys). This bundles key-create + webhook-URL composition so a UI (or a curl) can set up a trigger in a single step instead of two — the backend for the self-serve "Add trigger" button. The webhook then flows through the existing forward ingress unchanged. **Before** — wiring a trigger was two manual steps, and the caller had to know the agent's internal id, invent a secret, and hand-compose the forward URL: ```python # 1. register the signing key (need the agent's internal id + your own secret) POST /agent_api_keys { "agent_id": "<look-up-first>", "api_key": "<generate-yourself>", "name": "owner/repo", "api_key_type": "github" } # 2. hand-build the forward URL from the convention you have to know webhook_url = f"{public_url}/agents/forward/name/{agent_name}/github-pr/{config_id}" ``` **After** — one call, by agent **name**, returns the URL + secret ready to paste: ```python POST /agent_api_keys/webhook-trigger { "agent_name": "golden-agent", "source": "github", "name": "owner/repo", "forward_path": "github-pr/<config-id>" } → { "key_id": "...", "secret": "ab3f…", # generated for you, shown once "webhook_path": "/agents/forward/name/golden-agent/github-pr/<config-id>", "webhook_url": "https://<host>/agents/forward/name/golden-agent/github-pr/<config-id>" } ``` No new ingress, no migration — built on the existing `agent_api_keys` + forward mechanism. ## On the signing secret This matches how GitHub webhooks actually work. A GitHub webhook's **Secret** is a value *you* supply (GitHub doesn't generate one) — you type a high-entropy string into the webhook's Secret field, and GitHub uses it to HMAC each payload into `X-Hub-Signature-256: sha256=…`, which the receiver re-computes and compares. It's a shared secret that must exist on both sides (GitHub's config + the verifying server), and it's optional-but-recommended (no secret → no signature header at all). Refs: GitHub docs [validating-webhook-deliveries](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries), [creating-webhooks](https://docs.github.com/en/webhooks/using-webhooks/creating-webhooks). Given that, the endpoint's `secret` handling is deliberate: - **omit `secret`** (default) → the endpoint generates a strong one (`secrets.token_hex(32)`), stores it on the agent's verification key, and returns it once to paste into GitHub's Secret field — so the caller never has to invent entropy. - **supply `secret`** → for when the GitHub webhook already has a secret set and the agent side just needs to match it. ## Testing - 4 unit tests (URL composition, provided vs generated secret, 409 on duplicate, 400 on non-webhook source). ruff clean. 🤖 Generated with [Claude Code](https://claude.com/claude-code)  <h3>Greptile Summary</h3> Adds `POST /agent_api_keys/webhook-trigger`, a one-call endpoint that registers a GitHub/Slack signature-verification key for an agent and returns the ready-to-paste forward webhook URL and signing secret. Iterates on earlier review feedback (Slack secret enforcement, empty-string coercion fix, UUID leakage, log level, forward-path URL encoding). - **New endpoint + schemas**: `create_webhook_trigger` bundles key creation, `forward_path` URL encoding, and webhook URL composition into a single request; Slack sources require an explicit `secret`, GitHub auto-generates one if omitted. - **Validation & encoding**: `forward_path` control characters are rejected; `agent_name` and `forward_path` are percent-encoded with `urllib.parse.quote` before being embedded in the returned URL. - **Tests**: Eight unit tests covering the main flows, including URL encoding, Slack without secret, duplicate-key 409, and an empty-secret preserve check. <details><summary><h3>Confidence Score: 4/5</h3></summary> The new handler works correctly for all inputs except when forward_path contains a control character — in that case, the signing key is already committed to the database before the 400 is raised, leaving an orphaned key that blocks all retries with the same name. The forward_path control-character check runs after agent_api_key_use_case.create() rather than before it. A caller who sends a forward_path with a control character gets a 400 response and no key_id, while the key quietly persists. Any corrected retry then hits a 409 permanently. Moving the validation above the DB write is the full fix. All other previously raised concerns (Slack secret requirement, empty-string or coercion, UUID leak, log level) appear to have been addressed correctly. agentex/src/api/routes/agent_api_keys.py — the create_webhook_trigger handler needs the forward_path control-char check moved above agent_api_key_use_case.create(). </details> <details><summary><h3>Important Files Changed</h3></summary> | Filename | Overview | |----------|----------| | agentex/src/api/routes/agent_api_keys.py | New create_webhook_trigger handler correctly addresses prior review concerns (Slack secret, empty-string coercion, UUID leakage, log level), but has a sequencing bug: forward_path control-char validation fires after agent_api_key_use_case.create(), which can orphan a committed key and leave the caller unable to retry. | | agentex/src/api/schemas/agent_api_keys.py | New request/response schemas for webhook trigger; secret is str | None with updated description correctly documenting Slack requirement; no structural issues. | | agentex/tests/unit/api/test_webhook_trigger.py | Good unit-test coverage: URL composition, provided vs generated secret, 409 on duplicate, 400 on non-webhook source, Slack with/without secret, URL encoding, and control-char rejection. | | agentex/openapi.yaml | New /agent_api_keys/webhook-trigger path and schemas added; secret description updated to document Slack requirement; mirrors schema definitions correctly. | </details> </details> <details><summary><h3>Sequence Diagram</h3></summary> <a href="#gh-light-mode-only"> ```mermaid %%{init: {'theme': 'neutral'}}%% sequenceDiagram participant Caller participant Handler as create_webhook_trigger participant AuthSvc as AuthorizationService participant AgentUC as AgentsUseCase participant KeyUC as AgentAPIKeysUseCase Caller->>Handler: POST /agent_api_keys/webhook-trigger Handler->>Handler: validate source (github/slack) Handler->>AgentUC: "get(name=agent_name)" AgentUC-->>Handler: agent Handler->>AuthSvc: check agent update permission AuthSvc-->>Handler: ok / 404 Handler->>KeyUC: get_by_agent_id_and_name(...) KeyUC-->>Handler: existing key or None alt key exists Handler-->>Caller: 409 Conflict end Handler->>Handler: validate Slack requires secret Handler->>Handler: resolve secret (provided or token_hex) Handler->>KeyUC: create(agent_id, api_key, name, type) KeyUC-->>Handler: agent_api_key_entity Note over Handler: forward_path validated AFTER DB write Handler->>Handler: lstrip + control-char check Handler->>Handler: quote(agent_name) + quote(forward_path) Handler->>Handler: compose webhook_path + webhook_url Handler-->>Caller: "200 {key_id, secret, webhook_path, webhook_url}" ``` </a> <a href="#gh-dark-mode-only"> ```mermaid %%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%% sequenceDiagram participant Caller participant Handler as create_webhook_trigger participant AuthSvc as AuthorizationService participant AgentUC as AgentsUseCase participant KeyUC as AgentAPIKeysUseCase Caller->>Handler: POST /agent_api_keys/webhook-trigger Handler->>Handler: validate source (github/slack) Handler->>AgentUC: "get(name=agent_name)" AgentUC-->>Handler: agent Handler->>AuthSvc: check agent update permission AuthSvc-->>Handler: ok / 404 Handler->>KeyUC: get_by_agent_id_and_name(...) KeyUC-->>Handler: existing key or None alt key exists Handler-->>Caller: 409 Conflict end Handler->>Handler: validate Slack requires secret Handler->>Handler: resolve secret (provided or token_hex) Handler->>KeyUC: create(agent_id, api_key, name, type) KeyUC-->>Handler: agent_api_key_entity Note over Handler: forward_path validated AFTER DB write Handler->>Handler: lstrip + control-char check Handler->>Handler: quote(agent_name) + quote(forward_path) Handler->>Handler: compose webhook_path + webhook_url Handler-->>Caller: "200 {key_id, secret, webhook_path, webhook_url}" ``` </a> </details> <a href="https://app.greptile.com/api/ide/cursor?prompt=Fix%20the%20following%201%20code%20review%20issue.%20Work%20through%20them%20one%20at%20a%20time%2C%20proposing%20concise%20fixes.%0A%0A---%0A%0A%23%23%23%20Issue%201%20of%201%0Aagentex%2Fsrc%2Fapi%2Froutes%2Fagent_api_keys.py%3A163-176%0A**Key%20created%20before%20%60forward_path%60%20is%20validated**%20%E2%80%94%20if%20%60forward_path%60%20contains%20a%20control%20character%2C%20the%20DB%20write%20at%20line%20164%20has%20already%20committed%20before%20the%20400%20is%20raised.%20The%20caller%20receives%20an%20error%20response%20with%20no%20%60key_id%60%2C%20yet%20the%20key%20now%20exists%20under%20%60%28agent_id%2C%20name%2C%20source%29%60.%20Any%20subsequent%20corrected%20retry%20hits%20a%20409%20and%20is%20permanently%20blocked%20without%20deleting%20the%20orphaned%20key.%20Move%20the%20control-character%20check%20%28and%20the%20%60lstrip%60%29%20to%20before%20the%20%60create%28%29%60%20call.%0A%0A%60%60%60suggestion%0A%20%20%20%20forward_path%20%3D%20request.forward_path.lstrip%28%22%2F%22%29%0A%20%20%20%20if%20_has_control_chars%28forward_path%29%3A%0A%20%20%20%20%20%20%20%20raise%20HTTPException%28%0A%20%20%20%20%20%20%20%20%20%20%20%20status_code%3D400%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20detail%3D%22forward_path%20must%20not%20contain%20control%20characters.%22%2C%0A%20%20%20%20%20%20%20%20%29%0A%0A%20%20%20%20secret%20%3D%20request.secret%20if%20request.secret%20is%20not%20None%20else%20secrets.token_hex%2832%29%0A%20%20%20%20agent_api_key_entity%20%3D%20await%20agent_api_key_use_case.create%28%0A%20%20%20%20%20%20%20%20agent_id%3Dagent.id%2C%0A%20%20%20%20%20%20%20%20api_key%3Dstr%28secret%29%2C%0A%20%20%20%20%20%20%20%20name%3Drequest.name%2C%0A%20%20%20%20%20%20%20%20api_key_type%3Drequest.source%2C%0A%20%20%20%20%29%0A%60%60%60%0A%0A&pr=329&platform=github"><picture><source media="(prefers-color-scheme: dark)" srcset="https://greptile-static-assets.s3.amazonaws.com/badges/FixAllInCursorDark.svg?v=3"><source media="(prefers-color-scheme: light)" srcset="https://greptile-static-assets.s3.amazonaws.com/badges/FixAllInCursor.svg?v=3"><img alt="Fix All in Cursor" src="https://greptile-static-assets.s3.amazonaws.com/badges/FixAllInCursor.svg?v=3" height="20"></picture></a> <a href="https://app.greptile.com/ide/claude-code?prompt=Fix%20the%20following%201%20code%20review%20issue.%20Work%20through%20them%20one%20at%20a%20time%2C%20proposing%20concise%20fixes.%0A%0A---%0A%0A%23%23%23%20Issue%201%20of%201%0Aagentex%2Fsrc%2Fapi%2Froutes%2Fagent_api_keys.py%3A163-176%0A**Key%20created%20before%20%60forward_path%60%20is%20validated**%20%E2%80%94%20if%20%60forward_path%60%20contains%20a%20control%20character%2C%20the%20DB%20write%20at%20line%20164%20has%20already%20committed%20before%20the%20400%20is%20raised.%20The%20caller%20receives%20an%20error%20response%20with%20no%20%60key_id%60%2C%20yet%20the%20key%20now%20exists%20under%20%60%28agent_id%2C%20name%2C%20source%29%60.%20Any%20subsequent%20corrected%20retry%20hits%20a%20409%20and%20is%20permanently%20blocked%20without%20deleting%20the%20orphaned%20key.%20Move%20the%20control-character%20check%20%28and%20the%20%60lstrip%60%29%20to%20before%20the%20%60create%28%29%60%20call.%0A%0A%60%60%60suggestion%0A%20%20%20%20forward_path%20%3D%20request.forward_path.lstrip%28%22%2F%22%29%0A%20%20%20%20if%20_has_control_chars%28forward_path%29%3A%0A%20%20%20%20%20%20%20%20raise%20HTTPException%28%0A%20%20%20%20%20%20%20%20%20%20%20%20status_code%3D400%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20detail%3D%22forward_path%20must%20not%20contain%20control%20characters.%22%2C%0A%20%20%20%20%20%20%20%20%29%0A%0A%20%20%20%20secret%20%3D%20request.secret%20if%20request.secret%20is%20not%20None%20else%20secrets.token_hex%2832%29%0A%20%20%20%20agent_api_key_entity%20%3D%20await%20agent_api_key_use_case.create%28%0A%20%20%20%20%20%20%20%20agent_id%3Dagent.id%2C%0A%20%20%20%20%20%20%20%20api_key%3Dstr%28secret%29%2C%0A%20%20%20%20%20%20%20%20name%3Drequest.name%2C%0A%20%20%20%20%20%20%20%20api_key_type%3Drequest.source%2C%0A%20%20%20%20%29%0A%60%60%60%0A%0A&repo=scaleapi%2Fscale-agentex&pr=329&platform=github"><picture><source media="(prefers-color-scheme: dark)" srcset="https://greptile-static-assets.s3.amazonaws.com/badges/FixAllInClaudeDark.svg?v=3"><source media="(prefers-color-scheme: light)" srcset="https://greptile-static-assets.s3.amazonaws.com/badges/FixAllInClaude.svg?v=3"><img alt="Fix All in Claude Code" src="https://greptile-static-assets.s3.amazonaws.com/badges/FixAllInClaude.svg?v=3" height="20"></picture></a> <a href="https://app.greptile.com/api/ide/codex?prompt=IMPORTANT%3A%20Work%20in%20the%20repository%20%22scaleapi%2Fscale-agentex%22%20on%20the%20existing%20branch%20%22dm%2Fagentex-webhook-trigger%22.%20Checkout%20that%20branch%20%E2%80%94%20do%20NOT%20create%20a%20new%20branch%20or%20open%20a%20new%20PR.%20Push%20your%20changes%20to%20%22dm%2Fagentex-webhook-trigger%22.%0A%0AFix%20the%20following%201%20code%20review%20issue.%20Work%20through%20them%20one%20at%20a%20time%2C%20proposing%20concise%20fixes.%0A%0A---%0A%0A%23%23%23%20Issue%201%20of%201%0Aagentex%2Fsrc%2Fapi%2Froutes%2Fagent_api_keys.py%3A163-176%0A**Key%20created%20before%20%60forward_path%60%20is%20validated**%20%E2%80%94%20if%20%60forward_path%60%20contains%20a%20control%20character%2C%20the%20DB%20write%20at%20line%20164%20has%20already%20committed%20before%20the%20400%20is%20raised.%20The%20caller%20receives%20an%20error%20response%20with%20no%20%60key_id%60%2C%20yet%20the%20key%20now%20exists%20under%20%60%28agent_id%2C%20name%2C%20source%29%60.%20Any%20subsequent%20corrected%20retry%20hits%20a%20409%20and%20is%20permanently%20blocked%20without%20deleting%20the%20orphaned%20key.%20Move%20the%20control-character%20check%20%28and%20the%20%60lstrip%60%29%20to%20before%20the%20%60create%28%29%60%20call.%0A%0A%60%60%60suggestion%0A%20%20%20%20forward_path%20%3D%20request.forward_path.lstrip%28%22%2F%22%29%0A%20%20%20%20if%20_has_control_chars%28forward_path%29%3A%0A%20%20%20%20%20%20%20%20raise%20HTTPException%28%0A%20%20%20%20%20%20%20%20%20%20%20%20status_code%3D400%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20detail%3D%22forward_path%20must%20not%20contain%20control%20characters.%22%2C%0A%20%20%20%20%20%20%20%20%29%0A%0A%20%20%20%20secret%20%3D%20request.secret%20if%20request.secret%20is%20not%20None%20else%20secrets.token_hex%2832%29%0A%20%20%20%20agent_api_key_entity%20%3D%20await%20agent_api_key_use_case.create%28%0A%20%20%20%20%20%20%20%20agent_id%3Dagent.id%2C%0A%20%20%20%20%20%20%20%20api_key%3Dstr%28secret%29%2C%0A%20%20%20%20%20%20%20%20name%3Drequest.name%2C%0A%20%20%20%20%20%20%20%20api_key_type%3Drequest.source%2C%0A%20%20%20%20%29%0A%60%60%60%0A%0A&repo=scaleapi%2Fscale-agentex&pr=329&platform=github"><picture><source media="(prefers-color-scheme: dark)" srcset="https://greptile-static-assets.s3.amazonaws.com/badges/FixAllInCodexDark.svg?v=3"><source media="(prefers-color-scheme: light)" srcset="https://greptile-static-assets.s3.amazonaws.com/badges/FixAllInCodex.svg?v=3"><img alt="Fix All in Codex" src="https://greptile-static-assets.s3.amazonaws.com/badges/FixAllInCodex.svg?v=3" height="20"></picture></a> <details><summary>Prompt To Fix All With AI</summary> `````markdown Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes. --- ### Issue 1 of 1 agentex/src/api/routes/agent_api_keys.py:163-176 **Key created before `forward_path` is validated** — if `forward_path` contains a control character, the DB write at line 164 has already committed before the 400 is raised. The caller receives an error response with no `key_id`, yet the key now exists under `(agent_id, name, source)`. Any subsequent corrected retry hits a 409 and is permanently blocked without deleting the orphaned key. Move the control-character check (and the `lstrip`) to before the `create()` call. ```suggestion forward_path = request.forward_path.lstrip("/") if _has_control_chars(forward_path): raise HTTPException( status_code=400, detail="forward_path must not contain control characters.", ) secret = request.secret if request.secret is not None else secrets.token_hex(32) agent_api_key_entity = await agent_api_key_use_case.create( agent_id=agent.id, api_key=str(secret), name=request.name, api_key_type=request.source, ) ``` ````` </details> <sub>Reviews (6): Last reviewed commit: ["chore(agent\_api\_keys): update openapi sp..."](be8a6ab) | [Re-trigger Greptile](https://app.greptile.com/api/retrigger?id=38966389)</sub> > Greptile also left **1 inline comment** on this PR.  --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
diff --git a/agentex/openapi.yaml b/agentex/openapi.yaml
@@ -2722,6 +2722,47 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/HTTPValidationError'
+  /agent_api_keys/webhook-trigger:
+    post:
+      tags:
+      - Agent APIKeys
+      summary: Create Webhook Trigger
+      description: 'Wire a webhook trigger in one call.
+
+
+        Registers the source''s signature-verification key (github/slack) for the
+        agent and
+
+        returns the ready-to-paste forward webhook URL plus the signing secret (shown
+        once).
+
+        The webhook then flows through the existing /agents/forward ingress, which
+        verifies
+
+        the signature against this key. Bundles the existing key-create + URL composition
+        so
+
+        a UI (or a curl) can set up a trigger without two steps.'
+      operationId: create_webhook_trigger_agent_api_keys_webhook_trigger_post
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateWebhookTriggerRequest'
+        required: true
+      responses:
+        '200':
+          description: Successful Response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CreateWebhookTriggerResponse'
+        '422':
+          description: Validation Error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HTTPValidationError'
   /agent_api_keys/name/{name}:
     get:
       tags:
@@ -4549,6 +4590,93 @@ components:
             to the agent inside the ACP payload for backward compatibility.
       type: object
       title: CreateTaskRequest
+    CreateWebhookTriggerRequest:
+      properties:
+        agent_name:
+          type: string
+          title: Agent Name
+          description: The agent the webhook drives.
+        source:
+          $ref: '#/components/schemas/AgentAPIKeyType'
+          description: Webhook source whose signature is verified (github or slack).
+          default: github
+        name:
+          type: string
+          title: Name
+          description: 'Signature-lookup key: the repo full_name (github) or api_app_id
+            (slack) that the forward ingress matches the incoming webhook against.'
+        forward_path:
+          type: string
+          title: Forward Path
+          description: Subpath the agent's own route handles, e.g. 'github-pr/<config-id>'.
+            Appended to /agents/forward/name/{agent_name}/ to form the webhook URL.
+        secret:
+          anyOf:
+          - type: string
+          - type: 'null'
+          title: Secret
+          description: Signing secret. For GitHub, omit to generate one, or provide
+            an existing webhook secret. For Slack, this is required and must be the
+            Slack app's Signing Secret.
+        base_url:
+          anyOf:
+          - type: string
+          - type: 'null'
+          title: Base Url
+          description: Optional public agentex base URL for the returned webhook_url;
+            defaults to the AGENTEX_PUBLIC_URL env var.
+      type: object
+      required:
+      - agent_name
+      - name
+      - forward_path
+      title: CreateWebhookTriggerRequest
+      description: 'One-call setup for a webhook trigger: register the source''s signature
+        key and
+
+        get back the ready-to-paste forward webhook URL.'
+    CreateWebhookTriggerResponse:
+      properties:
+        key_id:
+          type: string
+          title: Key Id
+          description: The created agent API key id.
+        agent_name:
+          type: string
+          title: Agent Name
+          description: The agent the webhook drives.
+        source:
+          $ref: '#/components/schemas/AgentAPIKeyType'
+          description: Webhook source (github or slack).
+        name:
+          type: string
+          title: Name
+          description: Signature-lookup key (repo full_name / api_app_id).
+        secret:
+          type: string
+          title: Secret
+          description: The signing secret — shown once; paste into the source's webhook
+            config.
+        webhook_path:
+          type: string
+          title: Webhook Path
+          description: The forward path to POST webhooks to.
+        webhook_url:
+          anyOf:
+          - type: string
+          - type: 'null'
+          title: Webhook Url
+          description: Full webhook URL to paste into the source (None if no base
+            URL configured).
+      type: object
+      required:
+      - key_id
+      - agent_name
+      - source
+      - name
+      - secret
+      - webhook_path
+      title: CreateWebhookTriggerResponse
     DataContent:
       properties:
         type:
diff --git a/agentex/src/api/routes/agent_api_keys.py b/agentex/src/api/routes/agent_api_keys.py
@@ -1,4 +1,6 @@
+import os
 import secrets
+from urllib.parse import quote
 
 from fastapi import APIRouter, HTTPException, Query
 
@@ -7,6 +9,8 @@
     AgentAPIKey,
     CreateAPIKeyRequest,
     CreateAPIKeyResponse,
+    CreateWebhookTriggerRequest,
+    CreateWebhookTriggerResponse,
 )
 from src.api.schemas.authorization_types import (
     AgentexResourceType,
@@ -35,6 +39,10 @@
 )
 
 
+def _has_control_chars(value: str) -> bool:
+    return any(ord(char) < 32 or ord(char) == 127 for char in value)
+
+
 @router.post(
     "",
     response_model=CreateAPIKeyResponse,
@@ -93,6 +101,99 @@ async def create_api_key(
     )
 
 
+@router.post(
+    "/webhook-trigger",
+    response_model=CreateWebhookTriggerResponse,
+)
+async def create_webhook_trigger(
+    request: CreateWebhookTriggerRequest,
+    agent_api_key_use_case: DAgentAPIKeysUseCase,
+    agent_use_case: DAgentsUseCase,
+    authorization_service: DAuthorizationService,
+) -> CreateWebhookTriggerResponse:
+    """Wire a webhook trigger in one call.
+
+    Registers the source's signature-verification key (github/slack) for the agent and
+    returns the ready-to-paste forward webhook URL plus the signing secret (shown once).
+    The webhook then flows through the existing /agents/forward ingress, which verifies
+    the signature against this key. Bundles the existing key-create + URL composition so
+    a UI (or a curl) can set up a trigger without two steps.
+    """
+    if request.source not in (AgentAPIKeyType.GITHUB, AgentAPIKeyType.SLACK):
+        raise HTTPException(
+            status_code=400,
+            detail="source must be 'github' or 'slack' for a webhook trigger.",
+        )
+    agent = await agent_use_case.get(name=request.agent_name)
+
+    # No api_key resource exists yet, so gate on the parent agent (update).
+    await _check_agent_or_collapse_to_404(
+        authorization_service,
+        agent.id,
+        AuthorizedOperationType.update,
+    )
+
+    existing_api_key = await agent_api_key_use_case.get_by_agent_id_and_name(
+        agent_id=agent.id,
+        name=request.name,
+        api_key_type=request.source,
+    )
+    if existing_api_key:
+        # A duplicate is an expected client condition (409), not a server error, and the
+        # message avoids leaking the internal agent UUID the caller never supplied.
+        raise HTTPException(
+            status_code=409,
+            detail=f"A {request.source} webhook key named '{request.name}' already exists for this agent.",
+        )
+
+    # GitHub lets you supply (and we can generate) a per-webhook secret to paste into the
+    # repo's Secret field. Slack is different: it signs every request with the app's own
+    # Signing Secret, so the caller must supply that exact value — a generated one would
+    # never match, and validate_slack_delivery_webhook would reject every real delivery.
+    # (See PR #329 discussion.)
+    if request.source == AgentAPIKeyType.SLACK and not request.secret:
+        raise HTTPException(
+            status_code=400,
+            detail=(
+                "Slack triggers must supply 'secret' set to the Slack app's Signing Secret "
+                "(from your app credentials); it can't be generated."
+            ),
+        )
+
+    forward_path = request.forward_path.lstrip("/")
+    if _has_control_chars(forward_path):
+        raise HTTPException(
+            status_code=400,
+            detail="forward_path must not contain control characters.",
+        )
+
+    secret = request.secret if request.secret is not None else secrets.token_hex(32)
+    agent_api_key_entity = await agent_api_key_use_case.create(
+        agent_id=agent.id,
+        api_key=str(secret),
+        name=request.name,
+        api_key_type=request.source,
+    )
+
+    encoded_agent_name = quote(request.agent_name, safe="")
+    encoded_forward_path = quote(forward_path, safe="/")
+    webhook_path = f"/agents/forward/name/{encoded_agent_name}/{encoded_forward_path}"
+    base_url = (request.base_url or os.environ.get("AGENTEX_PUBLIC_URL", "")).rstrip(
+        "/"
+    )
+    webhook_url = f"{base_url}{webhook_path}" if base_url else None
+
+    return CreateWebhookTriggerResponse(
+        key_id=agent_api_key_entity.id,
+        agent_name=request.agent_name,
+        source=agent_api_key_entity.api_key_type,
+        name=request.name,
+        secret=str(secret),
+        webhook_path=webhook_path,
+        webhook_url=webhook_url,
+    )
+
+
 @router.get(
     "",
     response_model=list[AgentAPIKey],
diff --git a/agentex/src/api/schemas/agent_api_keys.py b/agentex/src/api/schemas/agent_api_keys.py
@@ -53,3 +53,57 @@ class CreateAPIKeyResponse(BaseModel):
         ...,
         description="The value of the newly created API key.",
     )
+
+
+class CreateWebhookTriggerRequest(BaseModel):
+    """One-call setup for a webhook trigger: register the source's signature key and
+    get back the ready-to-paste forward webhook URL."""
+
+    agent_name: str = Field(..., description="The agent the webhook drives.")
+    source: AgentAPIKeyType = Field(
+        AgentAPIKeyType.GITHUB,
+        description="Webhook source whose signature is verified (github or slack).",
+    )
+    name: str = Field(
+        ...,
+        description="Signature-lookup key: the repo full_name (github) or api_app_id "
+        "(slack) that the forward ingress matches the incoming webhook against.",
+    )
+    forward_path: str = Field(
+        ...,
+        description="Subpath the agent's own route handles, e.g. 'github-pr/<config-id>'. "
+        "Appended to /agents/forward/name/{agent_name}/ to form the webhook URL.",
+    )
+    secret: str | None = Field(
+        None,
+        description=(
+            "Signing secret. For GitHub, omit to generate one, or provide an existing "
+            "webhook secret. For Slack, this is required and must be the Slack app's "
+            "Signing Secret."
+        ),
+    )
+    base_url: str | None = Field(
+        None,
+        description="Optional public agentex base URL for the returned webhook_url; "
+        "defaults to the AGENTEX_PUBLIC_URL env var.",
+    )
+
+
+class CreateWebhookTriggerResponse(BaseModel):
+    key_id: str = Field(..., description="The created agent API key id.")
+    agent_name: str = Field(..., description="The agent the webhook drives.")
+    source: AgentAPIKeyType = Field(
+        ..., description="Webhook source (github or slack)."
+    )
+    name: str = Field(
+        ..., description="Signature-lookup key (repo full_name / api_app_id)."
+    )
+    secret: str = Field(
+        ...,
+        description="The signing secret — shown once; paste into the source's webhook config.",
+    )
+    webhook_path: str = Field(..., description="The forward path to POST webhooks to.")
+    webhook_url: str | None = Field(
+        None,
+        description="Full webhook URL to paste into the source (None if no base URL configured).",
+    )
diff --git a/agentex/tests/unit/api/test_webhook_trigger.py b/agentex/tests/unit/api/test_webhook_trigger.py
