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

# How monitoring works

> Learn how to use monitoring to listen for changes associated with subscribed businesses on Middesk's Identity Platform.

This guide describes how to use monitoring to listen for changes associated with subscribed businesses on Middesk's Identity Platform.

## Prerequisites

Before you begin:

* Ensure that you can authenticate against the Middesk API, create businesses, and ingest Middesk results with [webhooks](../quickstart)

## Learn the monitoring lifecycle

Monitoring flow · 2 phases

How monitoring works for a business

<title id="md-mon-title">
  How Monitoring Works
</title>

<desc id="md-mon-desc">
  A business moves through two phases: Verification (Middesk processes the business
  and delivers insights), then Monitoring (the business is subscribed via dashboard,
  auto-enable, or policy, changes are detected, and webhook notifications are sent).
</desc>

<defs>
  <path d="M 0 0 L 10 5 L 0 10 z" fill="var(--md-sky)" />

  <path d="M 0 0 L 10 5 L 0 10 z" fill="var(--md-violet)" />

  <path d="M 0 0 L 10 5 L 0 10 z" fill="var(--md-lime)" />
</defs>

<line x1="24" y1="36" x2="236" y2="36" />

<g transform="translate(320, 36)">
  <rect x="-80" y="-13" width="160" height="26" rx="13" />

  01 · Verification
</g>

<line x1="404" y1="36" x2="616" y2="36" />

<g transform="translate(180, 72)">
  <rect width="280" height="116" rx="10" />

  <text x="20" y="22">
    Middesk
  </text>

  <text x="20" y="46">
    Processes Business and
  </text>

  <text x="20" y="64">
    Delivers Insights
  </text>

  <g transform="translate(20, 80)">
    <rect width="104" height="20" rx="4" />

    needs\_review
  </g>
</g>

<line x1="24" y1="286" x2="240" y2="286" />

<g transform="translate(320, 286)">
  <rect x="-72" y="-13" width="144" height="26" rx="13" />

  02 · Monitoring
</g>

<line x1="396" y1="286" x2="616" y2="286" />

<g transform="translate(20, 410)">
  <rect width="180" height="100" rx="10" />

  <text x="16" y="20">
    Manual
  </text>

  <text x="16" y="42">
    Dashboard or API
  </text>

  <text x="16" y="58">
    enable Monitoring
  </text>

  <text x="16" y="80">
    For individual businesses
  </text>
</g>

<g transform="translate(230, 410)">
  <rect width="180" height="100" rx="10" />

  <text x="16" y="20">
    Automatic
  </text>

  <text x="16" y="42">
    Auto-enable
  </text>

  <text x="16" y="58">
    Monitoring
  </text>

  <text x="16" y="80">
    For all businesses
  </text>
</g>

<g transform="translate(440, 410)">
  <rect width="180" height="100" rx="10" />

  <text x="16" y="20">
    Policy
  </text>

  <text x="16" y="42">
    Policy enable
  </text>

  <text x="16" y="58">
    Monitoring
  </text>

  <text x="16" y="80">
    For matching businesses
  </text>
</g>

<g transform="translate(180, 590)">
  <rect width="280" height="88" rx="10" />

  <rect x="256" y="16" width="8" height="8" rx="2" />

  <text x="20" y="22">
    Middesk · State
  </text>

  <text x="20" y="50">
    Monitoring Enabled
  </text>

  <text x="20" y="68">
    Business subscribed to change detection
  </text>
</g>

<g transform="translate(80, 722)">
  <rect width="480" height="126" rx="8" />

  <text x="20" y="26">
    Monitoring can be enabled for the following event types:
  </text>

  <text x="24" y="52">
    bankruptcy.created
  </text>

  <text x="24" y="70">
    bankruptcy.updated
  </text>

  <text x="24" y="88">
    registration.created
  </text>

  <text x="24" y="106">
    registration.updated
  </text>

  <text x="264" y="52">
    watchlist_result.created
  </text>

  <text x="264" y="70">
    watchlist_result.updated
  </text>

  <text x="264" y="88">
    tin.created
  </text>

  <text x="264" y="106">
    tin.updated
  </text>
</g>

<g transform="translate(200, 896)">
  <rect width="240" height="66" rx="10" />

  <text x="20" y="20">
    Middesk
  </text>

  <text x="20" y="46">
    Change Detected
  </text>
</g>

<g transform="translate(160, 1014)">
  <rect width="320" height="86" rx="10" />

  <text x="20" y="22">
    Notification
  </text>

  <text x="20" y="48">
    Webhook event and
  </text>

  <text x="20" y="66">
    email notification sent
  </text>
</g>

Here's the typical lifecycle of a business with monitoring enabled:

1. A business gets created with the [POST /businesses endpoint](/api-reference/business-verification/businesses/create-a-business).

2) The business is subscribed to monitoring.
3) At some point in the future, a change to that business is detected. The business record updates.
4) Middesk sends a webhook event to registered webhook endpoint(s).
5) The client application ingests and evaluates the change in the business record.

## Monitor businesses

#### Subscribe a business

You can enable monitoring on Middesk businesses using four different strategies.

#### With the API

Use the [POST /monitor API](/api-reference/business-verification/monitoring/create-a-monitor-for-a-business) to create, update, and delete business monitors for fine-grained control within your application.

#### With the Dashboard

Manually enable monitoring on a business with a completed business verification order on the **Monitoring** tab of the Middesk [Dashboard](https://app.middesk.com/).

#### Set up and listen for monitoring webhook events

Depending on the type of monitor that you want to listen for, [register a new webhook](https://app.middesk.com/settings/webhooks) with the corresponding [event types](../monitor-activity/events) selected.

#### Consume and evaluate monitoring events

Webhook requests contain a few top level fields:

* `data`. Contains the event-specific payload and all the information about a monitoring event.

  > **Note**
  >
  > Event payloads represent the change identified in the business record rather than full business object. For more granular control, use event payloads.

* `id`.  The Middesk-generated identifier for the webhook. It's useful for debugging. Use it to search for pertinent webhook logs on the Middesk webhooks page.

* `type`. The type of webhook provided.

* `account_id`. The Middesk-generated identifier for the account the webhook is sent for. Useful if you route traffic across multiple Middesk accounts.

> **Info**
>
> When a monitoring event is triggered, the composite business record and business insights update.

While it's possible to consume monitoring-specific payloads ([example payloads](../monitor-activity/events)), for typical use cases, it's usually sufficient to retrieve the business associated with the event.

To retrieve the business associated with the event:

1. Access the business's ID using the `data.object.business_id` field included in the webhook payload.
2. [Retrieve the Middesk business](https://dash.readme.com/project/middesk/v1.0/refs/retrieve-a-business) using the [GET /businesses endpoint](/api-reference/business-verification/businesses/retrieve-a-business).

   The response includes the full business record.

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

> Learn how to use monitoring to listen for changes associated with subscribed businesses on Middesk's Identity Platform.