managing-agent-webhooks

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 operation-specific exit-0 receipt with the HTTP status and reconciliation guidance rather than a generic error that could trigger a duplicate mutation.
• Delete reports deleted: true only after a 200 JSON object with literal success: true. A false, missing, malformed, null, empty, oversized, or unreadable receipt means deletion was accepted but remains unconfirmed; list webhooks before treating the capability URL as removed or retrying.
• Normal update output additionally requires the returned webhook ID and enabled state to match the requested operation; normal rotate output requires the returned webhook ID to match. Canonical but contradictory 2xx records receive the same accepted/reconcile envelope and are never printed as ordinary success.
• Normal create output also requires returned name and enabled state to match. An explicitly supplied preprompt must round-trip exactly; when preprompt is omitted, the server-owned default is accepted only as a nonblank string, while missing, null, empty, whitespace-only, and non-string values are contradictory. Rotate first reads the current agent-bound record and reports ordinary success only when the returned canonical slug/URL changed; an unchanged result is accepted but requires reconciliation.