Webhooks

Applies to: Hosted session and Your runner (the agentrun events). The rest of the page covers every webhook.

A webhook sends a signed HTTP POST to your URL when something happens in your workspace. Workspace admins manage them in Settings -> Webhooks. Webhooks need the Pro plan or higher.

Events

Each webhook picks the events it wants. A webhook only receives the events you switch on.

EventSent when
projectA project is created, updated or deleted.
issueA task is created, updated or deleted.
issue_commentA comment on a task is created, updated or deleted.
cycleA sprint is created, updated or deleted, or a task is added to or removed from it.
moduleA module is created, updated or deleted, or a task is added to or removed from it.
agent_runAn agent run finishes.

What a delivery looks like

Every delivery is a JSON POST with these headers:

  • X-Ithura-Event: the event name, for example agent_run.
  • X-Ithura-Delivery: a unique id for this delivery.
  • X-Ithura-Signature: lowercase hex HMAC-SHA256 of the raw request body, using the webhook's secret key.

Check the signature before you trust a request. If your endpoint returns a status of 400 or higher, or does not answer, Ithura retries up to 5 times with a growing delay. A webhook that fails 10 times in a row is switched off and the workspace admins get an email. Each attempt shows up in the webhook's delivery list, where you can also retry one by hand.

The body has the same outer shape for every event:

{
  "event": "agent_run",
  "action": "succeeded",
  "webhook_id": "b6a1...",
  "workspace_id": "0f3c...",
  "data": { },
  "activity": {
    "field": "",
    "old_value": null,
    "new_value": null,
    "actor": { "id": "00000000-0000-0000-0000-000000000000", "display_name": "", "avatar": "" }
  }
}

Agent run finished

Switch on agent_run to hear when an agent run ends, so you can post to your own chat or start the next step in your own tools. The event is sent once per run, after the result is saved.

action tells you how the run ended:

ActionMeaning
succeededThe agent finished the work.
failedThe run failed. The reason is in summary.
askedThe agent stopped to ask a person. The question is in question.
no_changeThe agent looked and found nothing to change.

Runs of a hosted session send the same events as runs of your own runner. A webhook runner you registered under Your runner sends succeeded or failed when the runner reports back.

Example:

{
  "event": "agent_run",
  "action": "asked",
  "webhook_id": "b6a1...",
  "workspace_id": "0f3c...",
  "data": {
    "run_id": "4d2e...",
    "task": {
      "id": "9c71...",
      "ref": "WEB-142",
      "name": "Fix the date picker on small screens",
      "project_id": "1ab4..."
    },
    "agent": { "id": "77e0...", "name": "Claude" },
    "provider": "claude-code",
    "model": "claude-sonnet-5-5",
    "status": "asked",
    "summary": "Found two causes, need a decision on one.",
    "question": "Should the picker open full screen on phones?",
    "session_url": "https://example.com/session/1",
    "pr_url": "https://github.com/acme/web/pull/88",
    "cost_usd": 0.42,
    "started_at": "2026-11-15T09:12:03Z",
    "finished_at": "2026-11-15T09:20:41Z"
  }
}

Notes on the fields:

  • status is the same as action.
  • summary and question are short text. question is empty unless the run asked.
  • session_url and pr_url are empty when there is no session link or pull request.
  • cost_usd is null when the agent did not report a cost.
  • The payload never includes tokens, callback secrets or transcripts.