Webhooks

Two ways to set one up

A schedule can have a webhook of its own, which hears every session it starts. See Schedules.

Register an endpoint

const endpoint = await client.agents.webhooks.create({
  url: "https://example.com/hooks/latentstack",
  events: ["run.completed", "run.failed", "approval.requested"],
  description: "Production",
})
console.log(endpoint.id, endpoint.secret) // the secret is shown only now: store it

• The answer is the endpoint with its secret (whsec_…). It is shown only in this answer. Keep it with your receiver's settings.
• The endpoint hears the sessions you create in the organization you're working in. Other people in the organization have their own.
• Past the limit, create fails with endpoint_limit_reached. Delete one first.
• Change url, events, description or enabled later with webhooks.update(). The other fields keep their values.
• Deleting an endpoint marks the deliveries still waiting for it as failed.

A webhook for one session

Pass webhook when you create a session to hear about that session alone. This suits a job runner that starts one session per task and wants a callback to the task's own URL.

const session = await sessions.create({
  agent: { model: "anthropic/claude-sonnet-5.5" },
  input: "Fix the failing test in packages/core.",
  webhook: { url: "https://example.com/hooks/tasks/42", events: ["run.*", "session.stopped"] },
})
console.log(session.webhook?.secret) // made for you, shown only now

• events defaults to ["*"].
• The create answer has a webhook field: the endpoint, with session_id set. It has a secret only when LatentStack made one, and only in this answer.
• Or bring your own secret, so one receiver can verify every session with the same key. It is whsec_ followed by the base64 of 24 to 64 random bytes.
• It isn't listed with your registered endpoints and doesn't count toward their limit. Read, update, test and rotate it by its id like any other endpoint.
• Your registered endpoints hear the session too, for the types they subscribe to.
• It is removed 7 days after the session stops or fails, which is longer than the retries of its last events.

Events

In events, a family is the part before the dot: session.*, run.*, approval.*, question.*, limit.*, artifact.* or schedule.*. New event types can appear over time. Answer 2xx to any you don't recognise.

The envelope

Every delivery is one event, as JSON:

{
  "id": "evt_5b1f0c9e2a7d4e8f9a0b1c2d",
  "object": "event",
  "type": "run.completed",
  "api_version": "v1",
  "created_at": "2026-10-14T04:01:12.381000+00:00",
  "sequence": 6,
  "session": {
    "id": "ags_4843742656c9cbc90685c6d2",
    "status": "idle",
    "metadata": { "customer": "cus_123" },
    "stop_reason": null,
    "error": null,
    "limits": { "max_turns": null, "max_tokens": null, "max_cost_usd": 2.0, "spent": { … } },
    "instance_number": 1,
    "last_seq": 41,
    "schedule_id": null
  },
  "data": {
    "seq": 41,
    "last_message": "Done. The names are sorted in out/sorted.txt.",
    "patches": []
  }
}

A body is at most 256 KB. If an event would be larger, session.metadata is replaced by { "omitted": true, "reason": "…" }, and if that isn't enough, so is data. Read the session for the full picture. In artifact.ready, a list of more than 200 files is cut short with files_truncated: true.

Verify the signature

Anyone can send a POST to your URL, so check that a delivery came from LatentStack before you act on it. Each one is signed with the endpoint's secret. verifyWebhook (TypeScript) and verify_webhook (Python) check the signature and the time it was sent, and return the event. When a check fails they throw WebhookVerificationError.

import { createServer } from "node:http"
import { verifyWebhook } from "@latentcode/sandbox-agents"

const secret = process.env.LS_WEBHOOK_SECRET! // whsec_…, shown when you made the endpoint
const seen = new Set<string>() // event ids already handled; keep them in your database in production

createServer(async (req, res) => {
  // The raw body: the signature is over the exact bytes that were sent.
  const chunks: Buffer[] = []
  for await (const chunk of req) chunks.push(chunk)

  let event
  try {
    event = await verifyWebhook(Buffer.concat(chunks), req.headers, secret)
  } catch {
    res.writeHead(400).end()
    return
  }
  res.writeHead(200).end() // answer first, then do the work

  if (seen.has(event.id)) return // a retry carries the same id
  seen.add(event.id)
  if (event.type === "run.completed") console.log(event.session?.id, event.data?.last_message)
}).listen(8000)

• Pass the body exactly as it arrived, as bytes or a string. A body parsed as JSON and turned back into text won't match the signature.
• A delivery sent more than 5 minutes from your server's clock is refused, so an old delivery can't be replayed. Change it with toleranceSeconds (TypeScript) or tolerance_seconds (Python), in seconds.
• Neither helper makes a network call. In Python, verify_webhook is a plain function, so it works the same next to the async client.
• Run the Python receiver with uvicorn receiver:app --port 8000, and the TypeScript one with npx tsx receiver.ts. Both read the secret from LS_WEBHOOK_SECRET.

POST /hooks/latentstack HTTP/1.1
content-type: application/json
user-agent: latentstack-webhooks/1
webhook-id: evt_5b1f0c9e2a7d4e8f9a0b1c2d
webhook-timestamp: 1791950472
webhook-signature: v1,0eV36p6rL+HHnw+Z+xt0vUONglojAeIaGO0deTCGYn0=

{"id":"evt_5b1f0c9e2a7d4e8f9a0b1c2d","object":"event","type":"run.completed",…}

Answer fast, then do the work

• Answer with any 2xx status within 15 seconds. Anything else counts as a failure and is retried: another status, no answer in time, or a redirect (redirects aren't followed).
• Answer first and do the work afterwards: put the event on a queue, or in a background task as the example does. A handler that takes too long is retried even though it worked.
• Answer 2xx to events you don't handle too, so they aren't retried.
• Answer 410 Gone to turn the endpoint off.

Retries

A delivery that fails is tried again after 5 seconds, 30 seconds, 2, 5, 15 and 30 minutes, 1, 2 and 4 hours, then every 8 hours: 18 attempts over about three days. Each wait varies by up to a fifth, so retries from many sessions don't all arrive together. After the last attempt the delivery is failed. The event stays in the event log.

Order and duplicates

• Each event is delivered at least once. A retry, or an answer that was lost on the way back, can bring the same event twice. Dedupe on id.
• Events don't always arrive in order: a retried event can arrive after a later one. Within a session, order by sequence. Numbers can skip, so don't expect each one to be the last plus one.
• session is a snapshot from when the event happened. For the current state, read the session.

Where deliveries can go

• HTTPS on port 443 only.
• The host must resolve only to public internet addresses: no localhost and no private networks.
• No user name or password in the URL. The host is a plain ASCII name without a trailing dot; write an international domain in its xn-- form.
• The URL is checked when you set it, and again before every attempt.

To try a receiver on your own machine, expose it through an HTTPS tunnel that gives it a public address on port 443.

Delivery logs

Every attempt is recorded. Read what was sent to one endpoint, or what was sent about one session to every endpoint that heard it. Both are newest first and kept for 30 days.

const { data } = await client.agents.webhooks.deliveries(endpoint.id, { status: "failed" })
for (const d of data) console.log(d.event_type, d.attempts, d.last_attempt?.status_code, d.last_attempt?.error)

// What was sent about one session, to every endpoint
const sent = await sessions.webhookDeliveries(session.id)

Test, rotate and retry

const webhooks = client.agents.webhooks

// Send a webhook.test event now
const delivery = await webhooks.test(endpoint.id)

// Make a new secret. The old one keeps working for 24 hours.
const { secret } = await webhooks.rotateSecret(endpoint.id)

// Send a delivery again now, e.g. a failed one from the delivery log
await webhooks.retryDelivery(endpoint.id, deliveryId)

Tests and retries need the endpoint to be on; otherwise they fail with endpoint_disabled. Together they are limited to 60 a minute per person (rate_limited). A test fails with endpoint_backlogged when 1,000 deliveries are already waiting for the endpoint.

Catch up from the event log

Every event is also kept in a log for 30 days, whether or not an endpoint received it. After your receiver was down, or turned off, read the log from the last event you handled.

let after = lastHandledId // the id of the last event you handled, from your database
while (true) {
  const page = await client.agents.events.list({ after, limit: 100 })
  for (const event of page.data) await handle(event) // the same handler, deduping on id
  if (!page.has_more) break
  after = page.next_after!
}

• Events come oldest first, with the same body a delivery has, for your sessions and schedules in the organization you're working in.
• Filter with types (a comma-separated list; families and * work) and session_id.
• An event appears in the log a few seconds after it happens. Test events aren't listed.
• after must be an event still in the log. If your last id is more than 30 days old, start again without it.

Over HTTP

Lists hold 20 items by default (the event log 50), and up to 100. When has_more is true, pass next_after as after for the next page.