Webhooks and Queues
Three namespaces for work that happens without you watching. custom-webhooks lets an outside system trigger Autessa; workqueues drains a large batch through the worker fleet; conversation-sync archives closed agent conversations into a table. All three run server-side with no session attached, which makes them the durable half of building headless.
Inbound webhooks
A webhook exposes a public URL. An external system POSTs to it; the payload is transformed into named variables — via JSONPath mappings or an AutessaScript transform — and those variables are substituted into a target resource that runs asynchronously. The target can be a tool, an agent, a manager, or a direct AutessaDB operation.
How to create one
autessa custom-webhooks create --webhookConfig '{
"name": "Inbound lead",
"...": "..."
}'
create mints the webhook's API key and returns it exactly once. Capture it from that response — it is never returned by any read. If you lose it, refresh-api-key rotates to a new one, which means updating every caller.Run autessa custom-webhooks create help for the full webhookConfig shape; name is the only required field inside it.
How to manage and debug one
autessa custom-webhooks get-all
autessa custom-webhooks get --json '{...}'
autessa custom-webhooks update --json '{...}'
autessa custom-webhooks refresh-api-key --json '{...}'
autessa custom-webhooks delete --json '{...}'
update changes the configuration and/or the enabled flag — disable rather than delete while you are debugging, since delete is a hard delete.
The command that earns its keep:
autessa custom-webhooks get-execution-history --json '{...}'
Pages through inbound calls newest-first with status, timing, attempt number, and decrypted execution details — so you can see the payload that actually arrived rather than what the caller believes it sent. That is almost always where a "the webhook isn't working" investigation ends.
Sharing a webhook is web-app-only.
| Command | What it does |
|---|---|
| autessa custom-webhooks create | Create an inbound webhook and mint its API key. |
| autessa custom-webhooks delete | Permanently delete a webhook (hard delete). |
| autessa custom-webhooks get | Fetch one webhook's configuration by id. |
| autessa custom-webhooks get-all | List every webhook you can access in the current company — those you own plus those shared with you (company-wide or per-user). |
| autessa custom-webhooks get-execution-history | Page through a webhook's inbound execution history — status, timing, attempt number, and decrypted execution details — newest page first. |
| autessa custom-webhooks refresh-api-key | Rotate a webhook's API key. |
| autessa custom-webhooks share | Web appWebhook sharing is managed from the Autessa web app. |
| autessa custom-webhooks update | Update a webhook's configuration and/or its enabled flag. |
Work queues
Durable background processing. You create a queue, enqueue a batch, and the worker fleet drains it — enqueue returns immediately, so you poll progress rather than waiting.
How to create a queue
autessa workqueues create \
--name "Nightly enrichment" \
--description "Enriches new leads." \
--maxConcurrency 10 \
--defaultMaxAttempts 3 \
--defaultTimeoutSeconds 120
| Setting | Controls |
|---|---|
maxConcurrency | How many items are leased and running at once |
defaultMaxAttempts | Retries for items that don't override it |
defaultTimeoutSeconds | Per-item lease timeout — an item that exceeds it is retried |
stagePrecedence | Ordered stage names, so earlier stages lease first. Omit for plain FIFO-by-priority |
runtime | Where items run; defaults to WORKER |
Time fields are plain integers in seconds, not durations.
How to enqueue work
Each item names the published tool that processes it, plus a free-form payload:
autessa workqueues enqueue --queueId <id> --items '[
{ "groupKey": "run-2026-09-10", "actionToolId": "gPdJwp5jbr9eN", "payload": {"leadId": "1"} },
{ "groupKey": "run-2026-09-10", "actionToolId": "gPdJwp5jbr9eN", "payload": {"leadId": "2"} }
]'
groupKey is what makes a batch addressable afterwards — progress, cancellation and dead-item retries all operate on a group. Set it deliberately rather than leaving items ungrouped.
Build the action tool the usual way, preferring a purpose-built type over a script — see Tools.
How to watch it drain
autessa workqueues progress --queueId <id> --groupKey run-2026-09-10
Returns counts by state — pending, running, succeeded, failed, dead, cancelled — plus per-stage counts. This is your polling command.
autessa workqueues items-list --queueId <id> --json '{...}'
autessa workqueues items-get --json '{...}'
items-list filters by state, stage or groupKey; items-get returns one item's state, attempts, payload, result and last error.
How to intervene
autessa workqueues pause --queueId <id> # stop leasing
autessa workqueues resume --queueId <id>
autessa workqueues retry-dead --json '{...}' # requeue a group's DEAD items
autessa workqueues cancel-group --json '{...}'
Dead means an item exhausted its attempts. retry-dead requeues every dead item in a group for another run — the right move after you fix the underlying tool. cancel-group stops every not-yet-terminal item in a group being leased.
pause is the emergency brake: it stops leasing without losing queued work, so a runaway batch can be halted while you investigate and then resumed.| Command | What it does |
|---|---|
| autessa workqueues cancel-group | Cancel every not-yet-terminal item in a group (pending/running items stop being leased). |
| autessa workqueues create | Create a work queue in your company. |
| autessa workqueues enqueue | Enqueue a batch of items onto a queue. |
| autessa workqueues get | Fetch one queue by id. |
| autessa workqueues items-get | Fetch one item by id — its state, attempts, payload, result, and last error. |
| autessa workqueues items-list | List items on a queue, newest-relevant first, with optional filters (state, stage, groupKey) and pagination. |
| autessa workqueues list | List every work queue in your active company. |
| autessa workqueues pause | Pause a queue — its items stop being leased until you resume it. |
| autessa workqueues progress | Read aggregate progress for one group on a queue — item counts by state (pending, running, succeeded, failed, dead, cancelled) plus per-stage counts. |
| autessa workqueues resume | Resume a paused queue so its items lease again. |
| autessa workqueues retry-dead | Requeue every DEAD item in a group (items that exhausted their attempts) for another run. |
| autessa workqueues update | Update a queue's settings. |
Conversation sync
Company-scoped rules that copy a closed agent conversation's message log into an AutessaDB table row, as JSON, for reporting and analysis.
autessa conversation-sync create \
--name "Support transcripts" \
--agentIds '["K2UYSwk3Yy4i"]' \
--tableUpdates '[{...}]' \
--enabled true
autessa conversation-sync all
autessa conversation-sync get --json '{...}'
autessa conversation-sync update --json '{...}'
autessa conversation-sync delete --json '{...}'
Three things determine whether this does what you expect:
- It never syncs retroactively. A config applies only to conversations closed after it is written. Creating one does not backfill.
- It runs off the conversation-logged queue, asynchronously — not at config-write time. A conversation appears in the table some time after it closes.
- The destination is always an AutessaDB table. Never an external connector.
requiresEvaluation limits syncing to evaluated conversations, and allowSandboxConversations decides whether your own UI/sandbox runs are included — off by default, which is usually why a test conversation does not show up.
| Command | What it does |
|---|---|
| autessa conversation-sync all | List every conversation-sync config in your current company — enabled and disabled alike — each fully resolved with its agent filter, evaluation/sandbox settings, and table-update rules. |
| autessa conversation-sync create | Create a conversation-sync config scoped to your current company. |
| autessa conversation-sync delete | Permanently delete a conversation-sync config (irreversible). |
| autessa conversation-sync get | Fetch one conversation-sync config by id, fully resolved with its agent filter, evaluation/sandbox settings, and table-update rules. |
| autessa conversation-sync update | Update a conversation-sync config. |
Related
- Autessa CLI — why durable work belongs on the platform
- Scheduled jobs — the time-driven counterpart
- Tools — what a webhook or queue item runs
- AutessaDB — triggers, the row-change counterpart
- Webhook handlers in the builder