# Webhooks

## Create Webhook Trigger

**post** `/agent_api_keys/webhook-trigger`

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.

### Body Parameters

- `agent_name: string`

  The agent the webhook drives.

- `forward_path: string`

  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.

- `name: string`

  Signature-lookup key: the repo full_name (github) or api_app_id (slack) that the forward ingress matches the incoming webhook against.

- `base_url: optional string`

  Optional public agentex base URL for the returned webhook_url; defaults to the AGENTEX_PUBLIC_URL env var.

- `secret: optional string`

  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.

- `source: optional "internal" or "external" or "github" or "slack"`

  Webhook source whose signature is verified (github or slack).

  - `"internal"`

  - `"external"`

  - `"github"`

  - `"slack"`

### Returns

- `agent_name: string`

  The agent the webhook drives.

- `key_id: string`

  The created agent API key id.

- `name: string`

  Signature-lookup key (repo full_name / api_app_id).

- `secret: string`

  The signing secret — shown once; paste into the source's webhook config.

- `source: "internal" or "external" or "github" or "slack"`

  Webhook source (github or slack).

  - `"internal"`

  - `"external"`

  - `"github"`

  - `"slack"`

- `webhook_path: string`

  The forward path to POST webhooks to.

- `webhook_url: optional string`

  Full webhook URL to paste into the source (None if no base URL configured).

### Example

```http
curl http://localhost:5003/agent_api_keys/webhook-trigger \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $AGENTEX_SDK_API_KEY" \
    -d '{
          "agent_name": "agent_name",
          "forward_path": "forward_path",
          "name": "name"
        }'
```

#### Response

```json
{
  "agent_name": "agent_name",
  "key_id": "key_id",
  "name": "name",
  "secret": "secret",
  "source": "internal",
  "webhook_path": "webhook_path",
  "webhook_url": "webhook_url"
}
```

## Domain Types

### Webhook Create Webhook Trigger Response

- `WebhookCreateWebhookTriggerResponse object { agent_name, key_id, name, 4 more }`

  - `agent_name: string`

    The agent the webhook drives.

  - `key_id: string`

    The created agent API key id.

  - `name: string`

    Signature-lookup key (repo full_name / api_app_id).

  - `secret: string`

    The signing secret — shown once; paste into the source's webhook config.

  - `source: "internal" or "external" or "github" or "slack"`

    Webhook source (github or slack).

    - `"internal"`

    - `"external"`

    - `"github"`

    - `"slack"`

  - `webhook_path: string`

    The forward path to POST webhooks to.

  - `webhook_url: optional string`

    Full webhook URL to paste into the source (None if no base URL configured).