# Start a workflow from a webhook

Build a claim intake workflow that another system starts with one request, read the reply and the run's outcome, and pause it for a claims handler before a case is opened.

An event-triggered agent starts when something happens in another system. On Katonic it is a workflow with a webhook trigger: an address the other system sends a request to when the event happens. This tutorial builds claim intake. When a claim form arrives, the workflow extracts the details, checks them against the policy wording and prepares a recommendation for a claims handler. It is the fourth form in [Which builder for which agent](/agents/choose-a-builder).

**Who can use it:** the **Builder** role or higher, in a tenant licensed for agents and knowledge.

## Prerequisites

- A system that receives the claim form and can send an HTTP request when it does, and someone who can change that system.
- A knowledge source that holds the policy wording; see [Add a knowledge source](/knowledge/knowledge-bases/add-a-knowledge-source).
- A team you belong to, for the **Owner team**. The request that starts a run must come from a user who can use the workflow: its owner, a member of the owner team, or someone it is shared with. Ask your administrator how the calling system should obtain a token for such a user.

## Build the workflow

  
**Step 1. Start a blank workflow**

In Studio, open **My Agents** and select **New agent**. Select **Automate a process**, pick the **Blank** card and select **Continue to build**.

  
**Step 2. Name the flow and pick the owner**

On **Identity**, type the **Workflow name** `Claim Intake` and a **Description**, and pick the **Owner team**.

  
**Step 3. Set the webhook**

Open **Trigger** and select the **Webhook** card. In **Trigger label**, type `Claim form received`. In **Path**, type `/hooks/claim-intake`. The path is kept with the trigger as a name for the event; the address to call is shown after you publish.
    ![The workflow builder on Trigger for a draft named Claim Intake: the cards for how the workflow starts with Webhook selected, a Trigger label field and a Path field holding a path, and the Workflow draft rail on the right.](https://docs.katonic.ai/img/agents/forms/start-from-a-webhook/forms-webhook-trigger.png)
*A webhook trigger takes a path. The system that receives the claim form posts to it to start a run.*

  
**Step 4. Name the steps and give them their text**

Open **Steps**. Open the **LLM** step the flow starts with, a step that sends text to a model, and fill in the first block below. Then use **Add a step** twice: **Knowledge**, then **LLM**.

```text
Step name: Extract the claim details
Instruction: Read the claim form and list the claimant, the policy number, the date of loss, what happened and the amount claimed. Write "not stated" for anything the form does not say.

Step name: Find the policy wording
Knowledge base: the source that holds the policy wording

Step name: Write the recommendation
Instruction: Compare the claim details with the policy wording you are given. Recommend one of: accept, refer or decline. Give the clause each reason rests on. You do not decide the claim.
```

  
**Step 5. Add the approval**

Open **Branches & approvals** and select **Add approval**. In **Approval label**, type `Claims handler review`. In **Reviewers / channel**, type the channel to notify, here `#claims-handlers`. The run pauses at this step until a reviewer decides. You should now see the **Workflow draft** rail count one approval.
    ![The workflow builder on Branches & approvals with one approval gate: an Approval label field and a Reviewers / channel field, both filled, a Remove control, the Add branch and Add approval buttons, and the Workflow draft rail counting one approval.](https://docs.katonic.ai/img/agents/forms/start-from-a-webhook/forms-webhook-approval.png)
*An approval gate pauses the run for a person. Name the gate and the reviewers or channel to notify.*

  
**Step 6. Name the output and set the guardrails**

Open **Output**. In **Output label**, type `Case recommendation`, and in **Destination**, `return to caller`. Open **Guardrails** and switch on **Customer-facing tone & PII**, because a claim form carries personal data.

## Test and publish

  
**Step 1. Run the draft**

Open **Test**, paste the text of a claim form as the message and select **Run**. Every step reports in the **Run trace**. The sandbox continues the approval automatically, so this run does not prove the pause.

  
**Step 2. Publish with the API channel on**

Select **Publish**. Under **Where it runs**, tick **REST API** as well as **Work Room**: the address is shown only for an agent with the API channel on. [Before you build a form of agent](/agents/forms/before-you-build) covers the outcomes of a publish.

  
**Step 3. Copy the address**

Open the workflow from **My Agents** and select **Run**. Under **Triggers**, the **Webhook** card shows the address and the body to send. Select **Copy**.
    ![The Run tab of the published Claim Intake workflow, scrolled to Triggers: the Webhook card showing the trigger node value, the address to post to with a Copy button, and the shape of the request body.](https://docs.katonic.ai/img/agents/forms/start-from-a-webhook/forms-webhook-run.png)
*After publishing with the API channel on, the Webhook card shows the address to post to and the body to send.*

## Call the webhook

The address carries the workflow's id, not the path you typed. The calling system sends the claim as `message` inside `input_payload`, with a bearer token, a secret sent in the `Authorization` header to prove who is calling:

```bash
curl -X POST "https://<your tenant host>/api/admin/v1/agents/<agent id>/runs" \
  -H "Authorization: Bearer <token of a user who can use the workflow>" \
  -H "Content-Type: application/json" \
  -d '{"trigger_type": "webhook", "input_payload": {"message": "Claim form: policy HP-20418, water damage on 14 November, 2,300 claimed ..."}}'
```

The call returns at once with the new run, before any step has run:

```json
{
  "id": "<run id>",
  "agent_id": "<agent id>",
  "trigger_type": "webhook",
  "status": "pending",
  "total_steps": 0,
  "completed_steps": 0,
  "output_payload": {}
}
```

To learn the outcome, the caller keeps the `id` and reads `GET` on the same address followed by `/<run id>`. The reply carries the `status`, the steps completed, each step's output and, at the end, `output_payload`. A status of `pending`, `running` or `awaiting_approval` means the run is not finished. Every request starts a new run, so the calling system must send each claim once.

## Verify

Send the sample request. Then:

- The reply has an `id` and the status `pending`.
- On the **Run** tab, the run appears in **Run history** and moves through the three steps, then stops at **Claims handler review**.
- A reviewer finds it in the Work Room under **Automations**, on the **Needs approval** chip, where a webhook run is listed as **From a connected app**. The person who started a run cannot approve it.
- After the approval, the run completes and its output is the recommendation, with a clause beside each reason.

## Troubleshooting

- **The Webhook card says the API surface is disabled.** Publish again with **REST API** ticked.
- **The request is refused with 401.** The token is missing or has expired.
- **The request is refused with 404.** The agent id in the address is wrong, or the token's user has no access to the workflow at all. Add the user to the owner team.
- **The request is refused with 403.** The user can see the workflow but may only view it. Share it with them for use, or add them to the owner team.
- **The run stays at awaiting approval.** Nobody has decided. Check that the reviewers can see it under **Automations**; see [Automations and approvals](/user-guide/work-room/automations-and-approvals).
- **The recommendation ignores the policy.** Open the run and read the Knowledge step's output. If it is empty, the comparison had nothing to work from.

## Related

- [Which builder for which agent](/agents/choose-a-builder)
- [Automate a process](/agents/automate-a-process)
- [Automations and approvals](/user-guide/work-room/automations-and-approvals)
- Next form: [Call an agent from another system](/agents/forms/call-an-agent-from-another-system)

Source: https://docs.katonic.ai/agents/forms/start-from-a-webhook
