Include webhook_url in CreateWebhookResponse

[scoropeza]

Follow-up from PR #52 — surfaced during hands-on deploy-validation (Scenario 12). Small, self-contained DX fix.

Functional description

bgagent webhook create returns only the webhook ID and one-time secret:

$ bgagent webhook create --name "sam-demo" --output json
{
  "webhook_id": "01KQTGSYB8MTN3M82DY0GFBZKY",
  "name": "sam-demo",
  "secret": "...",
  "created_at": "2026-05-04T22:12:41.449Z"
}

The response does not include the POST URL the caller needs to invoke when configuring an external webhook (GitHub, CI pipeline, Slack workflow, etc.). To wire the webhook up (or smoke-test it with curl), the user has to:

1. Know or guess that the webhook endpoint path is /webhooks/tasks.
2. Read ~/.bgagent/config.json to find the api_url the CLI is configured against, and strip any trailing slash.
3. Concatenate the two manually.

User-visible impact:

• A new user cannot complete webhook wiring without reading the CDK construct code or hunting through CLI config. The webhook create flow is effectively incomplete.
• Automation that programmatically creates webhooks (e.g. a bulk provisioning script across dev / staging / prod stacks) has to hard-code or re-derive the URL per environment, which breaks cleanly.

For a feature whose entire purpose is to be configured into an external system, requiring the caller to synthesise the destination URL is a DX failure.

Technical fix

API side — add webhook_url: string to CreateWebhookResponse in cdk/src/handlers/shared/types.ts. The URL is trivially derivable server-side from the request host:

const webhookUrl = `https://${event.headers.Host}/${event.requestContext.stage}/webhooks/tasks`;
// or from process.env.API_URL if the stack exports it to the Lambda

CLI side:

• Add webhook_url to the mirror type in cli/src/types.ts.
• Surface webhook_url in the text formatter (cli/src/format.ts::formatWebhookCreated) alongside the existing Webhook: / Name: / Created: / Secret: rows.
• Document in the CLI help text that the URL is stable for the lifetime of the API deployment (not per-webhook), so callers do not re-fetch on every use.

Acceptance criteria

• POST /v1/webhooks returns a webhook_url field in the 201 response body.
• bgagent webhook create --output json | jq .webhook_url prints a non-null, fully-qualified HTTPS URL ending in /webhooks/tasks.
• bgagent webhook create (text output) shows the URL with a one-line hint that it is the endpoint to wire into the external system's webhook settings.
• Existing bgagent webhook list and bgagent webhook revoke paths unchanged — the URL is deployment-wide, not per-webhook, so no storage changes on WebhookTable.

Out of scope

• Surfacing the URL in webhook list entries (URL is stack-wide, not per-webhook; adding it per-row would be noise).
• GitHub webhook event-shape adapter (separate future issue; the missing URL is blocking progress on that too, but the fixes are independent).

References

• cdk/src/handlers/create-webhook.ts — response construction
• cdk/src/handlers/shared/types.ts:398-406 — CreateWebhookResponse interface
• cli/src/types.ts — CreateWebhookResponse mirror
• cli/src/format.ts::formatWebhookCreated
• PR feat(interactive-agents): async-only background task UX + Cedar HITL design #52 Scenario 12 hands-on testing transcript