aws-samples / aws-samples/sample-autonomous-cloud-coding-agents

Include webhook_url in CreateWebhookResponse

Open
#57 0 comments 0 reactions 0 assignees View on GitHub
cli orchestration
Dominant language
TypeScript
Stars
143
Forks
46
Avg merge
3d 9h
Merged PRs (30d)
20

Description

> **Follow-up from [PR #52](https://github.com/aws-samples/sample-autonomous-cloud-coding-agents/pull/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:

```console
$ 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:

```ts
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 #52 Scenario 12 hands-on testing transcript

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.