> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.middesk.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.middesk.com/_mcp/server.

# Webhook events

> Webhook events for agent run lifecycle changes.

Agent runs are asynchronous — they may take seconds, minutes, or hours depending on the work the agent performs. Subscribe to agent webhook events to receive real-time updates about run lifecycle changes instead of polling the [Run](/reference/run) endpoint.

Configure [webhooks](/build/webhooks) to receive notifications when agent runs are created, completed, or interrupted. These events use the same delivery pipeline as Middesk's other webhook events: identical retry behavior, authentication options, and `2xx` success contract. See [Implement webhooks](/build/webhooks) for setup details and [Secure webhooks](/build/secure-webhooks) for signature verification.

When a run interrupts, your endpoint receives the agent's open question and proposed artifacts so you can [take action](/work-with-agents/take-action) before the run resumes.

## Choosing events by review model

The events you need depend on where your team reviews agent findings:

| Review model                                                                   | Events to subscribe                   | Optional        |
| :----------------------------------------------------------------------------- | :------------------------------------ | :-------------- |
| Review in your own system                                                      | `run.interrupted`, `business.updated` | `run.completed` |
| Review in the Middesk Dashboard                                                | `business.updated`                    | `run.completed` |
| Fully automated with an [interrupt policy](/work-with-agents/interrupt-policy) | `business.updated`                    | `run.completed` |

Each event has one job:

* `run.interrupted` asks for your input. Subscribe when your own system presents findings to reviewers and responds through [Take action](/work-with-agents/take-action). If reviews happen in the Middesk Dashboard, or an interrupt policy resolves them automatically, you can skip it.
* `business.updated` tells you the Business record may have changed after a review is resolved. Note: runs that error or propose nothing never send `business.updated`.
* `run.completed` tells you a run is finished, whatever the outcome. It fires once for every run, including runs that error or never propose changes. Subscribe when your workflow waits on runs to finish.

## Receiving agent outcomes

For agent work, `business.updated` signals that an agent result was finalized or that its screenshot evidence finished settling. Middesk sends the first event after findings are `accepted`, `corrected`, `excluded`, or `skipped`, whether a reviewer resolved the review or an interrupt policy did. If web evidence screenshots are pending, Middesk sends another event after capture finishes.

Use the event as a signal to refresh your stored Business.

By default, the `business.updated` payload doesn't identify agent runs. To see which runs contributed to an update, add the `runs` field with a [custom event schema](/build/webhooks#customize-webhook-payloads), then pass the run `id` to [Retrieve an agent run](/api-reference/agents/runs/get-agent-run) for full details.

To identify the [agent result](/work-with-agents/review-work) behind an update and check its screenshot capture status, select `agent_applications` in the custom event schema:

**`Agent application webhook fields`**

```graphql title="Agent application webhook fields"
{
  id
  agent_applications {
    run_id
    screenshot_captures {
      settled_at
    }
  }
}
```

## Run events

| Event type        | Description                                                                                        |
| :---------------- | :------------------------------------------------------------------------------------------------- |
| `run.created`     | Sent when a [Run](/reference/run) is created and begins executing.                                 |
| `run.completed`   | Sent when a Run finishes with a status of `completed` or `error`.                                  |
| `run.interrupted` | Sent when a Run pauses and is waiting for input. See [Take action](/work-with-agents/take-action). |

### Sample payloads

Run events also include the `X-Correlation-ID` header, using the same convention
as `business.updated`: the business's `external_id` when set, otherwise the
Middesk business id. When a run is started with an inline `business` payload for
a business that does not exist yet, `run.created` has `"business_id": null`;
later `run.interrupted` and `run.completed` events include the business id after
the run's context is backfilled.

**`run.created`**

```json title="run.created"
{
  "object": "event",
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "type": "run.created",
  "data": {
    "object": {
      "object": "run",
      "id": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
      "business_id": null,
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z",
      "status": "running",
      "started_at": "2026-01-15T12:00:01.000Z",
      "ended_at": null,
      "steps": [],
      "interrupts": []
    }
  },
  "created_at": "2026-01-15T12:00:01.000Z"
}
```

**`run.completed`**

```json title="run.completed"
{
  "object": "event",
  "id": "b2c3d4e5-6789-01ab-cdef-2345678901ab",
  "type": "run.completed",
  "data": {
    "object": {
      "object": "run",
      "id": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
      "business_id": "68b56939-cfc5-4e8c-af0b-51e84d413670",
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:05:00.000Z",
      "status": "completed",
      "started_at": "2026-01-15T12:00:01.000Z",
      "ended_at": "2026-01-15T12:05:00.000Z",
      "steps": [],
      "interrupts": []
    }
  },
  "created_at": "2026-01-15T12:05:00.000Z"
}
```

**`run.interrupted`**

```json title="run.interrupted"
{
  "object": "event",
  "id": "c3d4e5f6-7890-12ab-cdef-3456789012ab",
  "type": "run.interrupted",
  "data": {
    "object": {
      "object": "run",
      "id": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
      "business_id": "68b56939-cfc5-4e8c-af0b-51e84d413670",
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:03:00.000Z",
      "status": "interrupted",
      "started_at": "2026-01-15T12:00:01.000Z",
      "ended_at": null,
      "steps": [],
      "interrupts": [
        {
          "id": "a8b3d2e1f4c6907856ab1234cdef5678",
          "agent": "address_verification",
          "value": {
            "agent": "address_verification",
            "label": "Add verified address sources to the report?",
            "artifacts": [
              {
                "title": "456 Market St, San Francisco, CA 94105",
                "type": "address",
                "confidence": "strong",
                "summary": "A state employer record confirms the business operates at 456 Market St, San Francisco, CA 94105.",
                "sources": [
                  {
                    "url": "https://example.com/employer-details/283947561",
                    "source_name": "Example State Agency",
                    "source_label": "Employer Record",
                    "source_tier": "government",
                    "source_type": "professional_license"
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  },
  "created_at": "2026-01-15T12:03:00.000Z"
}
```

> **Get a demo**
>
> Contact your account manager or [contact sales](https://www.middesk.com/contact-sales) to inquire about access.