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.
| Event | Sent when |
|---|---|
project | A project is created, updated or deleted. |
issue | A task is created, updated or deleted. |
issue_comment | A comment on a task is created, updated or deleted. |
cycle | A sprint is created, updated or deleted, or a task is added to or removed from it. |
module | A module is created, updated or deleted, or a task is added to or removed from it. |
agent_run | An agent run finishes. |
What a delivery looks like
Every delivery is a JSON POST with these headers:
X-Ithura-Event: the event name, for exampleagent_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:
| Action | Meaning |
|---|---|
succeeded | The agent finished the work. |
failed | The run failed. The reason is in summary. |
asked | The agent stopped to ask a person. The question is in question. |
no_change | The 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:
statusis the same asaction.summaryandquestionare short text.questionis empty unless the run asked.session_urlandpr_urlare empty when there is no session link or pull request.cost_usdisnullwhen the agent did not report a cost.- The payload never includes tokens, callback secrets or transcripts.