/managing-agent-webhooks

name: managing-agent-webhooks
description: Creates, lists, tests, enables, disables, rotates, inspects, and deletes inbound webhooks for the current Letta Cloud agent. Use when a user asks to set up a webhook, send external events to an agent, test webhook delivery, inspect recent webhook requests, rotate a webhook URL, or remove a webhook.

Managing Agent Webhooks

Use the helper script for deterministic, secret-safe webhook management. Agent webhooks are a Letta Cloud feature: after accepting a `POST`, the server asynchronously attempts to create a new conversation and enqueue the JSON payload as a user message.

Safety

• Manage the current agent only. `AGENT_ID` must be present, and the helper

does not accept an agent-ID override.

• Treat each webhook URL as a capability secret. Do not post it publicly.
• Choose authentication deliberately. If the user did not specify public or

Basic-auth access, ask before creating the webhook.

• For normal secured creation, let the helper generate the credential and use

`--credential-output` to write it to a new `0600` file before creating the webhook. The helper never prints the credential. Do not read or paste the file into the transcript.

• Give the file to the user through a private file download. On a Cloud

computer, create it under `/root/downloads` and return a sandbox download link in the form `[filename](#letta-sandbox-download//root/downloads/filename)`. Do not write credentials beneath an attacker-writable parent. Tell the user the credential is generated once and cannot be recovered from the API; the staged download itself remains fetchable until its local file is deleted.

• Never put a security key on the command line or in chat. A user-supplied key

is an advanced alternative and must be piped through stdin from an agent secret or another non-printing source.

• The helper redacts the one-time `authorization_header` returned by the API

from stdout and stores it only in the requested credential file.

• Management and ingress responses are untrusted. The helper allowlists safe

webhook/error fields; normalizes camelCase and punctuation before classifying secret-bearing property names; recursively redacts their values plus the exact generated key, Basic header, encoded credential, and management token; then redacts structurally before serialization so low-entropy secret values cannot rewrite JSON syntax or envelope semantics. Promised schema keys are preserved only at locally constructed, type-validated object paths; untrusted keys and values are still redacted. Safe output-field exemptions apply only to those trusted paths; untrusted `token_count` and similar fields receive normal secret-name redaction. Successful ingress response bodies are never displayed, validated for display, or summarized; test output uses only a locally constructed status/acceptance envelope. Serialized output is capped at 1 MiB; accepted side effects whose body exceeds that limit emit a bounded success envelope rather than a failure that could invite a duplicate retry.

• Response ingestion is also capped at 1 MiB. The helper stops reading and does

not parse or trust any prefix once that limit is exceeded; side-effect receipts become bounded accepted-but-unconfirmed output.

• Every management request rejects redirects. Every returned webhook URL is

validated before it can be displayed or used for delivery: it must use the active runtime's canonical origin and exactly `/v1/agent-webhooks/<returned-slug>`, with no URL credentials, query, fragment, malformed slug, or redirect. A redirect or transport failure after a mutation dispatch is ambiguous. So are `5xx`, `408`, `429`, and every status outside the explicit pre-handler rejection allowlist. Reconcile before retrying and never treat a redirect target or non-definitive status as proof that the mutation did nothing.

• Every returned webhook record must belong to the authoritative runtime

`AGENT_ID`. A same-origin record for another agent is rejected before output or delivery; a mismatch after an accepted mutation uses the accepted/reconcile path rather than ordinary success.

• Rotating invalidates the old URL. Deleting is permanent. Use the required

`--confirm` flag only after the user has approved that exact action.

• Request bodies may contain sensitive third-party data. `requests` omits them

unless `--include-body` is explicitly passed. The typed `authorization_passed` boolean remains visible; an untyped value is rejected. History output is constructed only from typed `id`, `status_code`, `authorization_passed`, `enqueued`, nullable `error_message`, and `created_at`, plus the locally derived `accepted`; `enqueued` is validated but intentionally omitted, and alternate body-like or future server fields are never spread into stdout.

• Sending a test starts asynchronous agent work. Ask for affirmative consent

before passing `--confirm`; do not treat general webhook setup approval as permission to trigger a test run.

• If test delivery is ambiguous, webhook state and request history cannot

reliably prove whether asynchronous agent work started. Do not retry without renewed affirmative user consent and explicit acceptance of duplicate-work risk.

• After a secure-create request is dispatched, any transport failure, 5xx, or

unreadable/truncated/contradictory success response is ambiguous. The helper validates the returned authentication mode for public, generated-key, and user-supplied-key creation, plus the returned Basic header for both secured modes. It preserves generated credentials and tells you to list webhooks and reconcile the name before any retry. Never blindly retry an ambiguous create.

• For test, update, rotate, and delete, successful HTTP headers establish that

the side effect was accepted. If the success body is truncated, malformed, or cannot be validated, the helper emits an