Substructure Webhooks

generated: '2026-10-19'
method: searched
generator: extract-docs-artifacts.py (local)
source: https://substructure.ai/llms.txt/docs/events-url.md
sources:
- https://substructure.ai/llms.txt/docs/events-url.md
- https://substructure.ai/llms.txt/docs/events.md
- https://substructure.ai/docs/events-url
- https://substructure.ai/docs/events
description: 'Substructure events URL delivers batches of logged events and live text to a configured URL. Each POST includes an HMAC‑SHA256 signature
  in the `X-Substructure-Signature: sha256=<hex>` header. The engine expects a `2xx` response; otherwise it retries with exponential backoff,
  honoring a `Retry-After` header (seconds). Retries continue for up to three days, after which the event is marked `delivery.skipped`. Successful
  delivery after failures is logged as `delivery.recovered`.'
events:
- event: session.created
  description: The session exists.
- event: message.new
  description: A message joined the tree.
- event: head.moved
  description: The active leaf changed.
- event: turn.started
  description: A turn began.
- event: turn.completed
  description: A turn ended, with its cost and output.
- event: session.done
  description: The session finished its work.
- event: session.cancelled
  description: The current run was cancelled.
- event: llm.call.requested
  description: A call was recorded.
- event: llm.call.dispatched
  description: The call went out.
- event: llm.call.completed
  description: The call returned.
- event: llm.call.errored
  description: The call failed.
- event: tool.call.requested
  description: The model asked for a tool.
- event: tool.call.dispatched
  description: The call went to its handler.
- event: tool.call.completed
  description: The call returned.
- event: tool.call.errored
  description: The call failed.
- event: subagent.requested
  description: The model called a child agent.
- event: subagent.dispatched
  description: The spawn went out.
- event: subagent.started
  description: The child session exists.
- event: subagent.turn_completed
  description: The child's turn ended.
- event: subagent.errored
  description: The child failed.
- event: connector.sync.requested
  description: Fetching a connection's tools.
- event: connector.sync.completed
  description: The tools arrived.
- event: connector.sync.errored
  description: The fetch failed.
- event: session.interrupted
  description: An interrupt occurred.
- event: session.interrupt_resumed
  description: An interrupt was resumed.
- event: worker.state.updated
  description: A decision wrote new state.
- event: agent.updated
  description: A decision wrote a new config.
- event: context.limited
  description: A model call waits for room.
- event: context.replaced
  description: History was set on a new branch.
- event: context.kept
  description: The held call runs on the current history.
- event: decision.queued
  description: A decision is waiting for the slot.
- event: decision.dispatched
  description: The request went to the worker.
- event: decision.completed
  description: The worker answered.
- event: decision.errored
  description: The decision failed.
- event: decision.dropped
  description: The decision was abandoned.
- event: call.voided
  description: A call was canceled before it settled.
- event: session.message_requested
  description: A message.send targeted another session.
- event: work.unsent
  description: Work could not be queued and will be retried.
- event: delivery.failed
  description: Delivery to a subscription failed; a retry will follow.
- event: delivery.recovered
  description: Delivery works again after failures.
- event: delivery.skipped
  description: The reader gave up on that event after retries.
- event: delivery.parked
  description: The reader stopped until resumed.
- event: delivery.resumed
  description: A parked reader runs again.
- event: branch.loaded
  description: A branch came back into memory.
- event: branch.unloaded
  description: Branches off the active path left memory.
delivery:
  signature: 'X-Substructure-Signature: sha256=<hex>'
  retries: Engine retries with backoff, using a Retry-After header (seconds). Retries continue for up to three days, then the event is marked
    delivery.skipped. Successful retry after failure is logged as delivery.recovered.
docs: https://substructure.ai/llms.txt/docs/events-url.md