> 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.

# Monitor status

> Learn how to handle changes to registration status.

Monitor for changes to the registration(s) associated with the business you're monitoring.

To handle changes to a business's registrations, subscribe to the `registration.created` and `registration.updated` events in your webhook endpoint.
Use this to detect a change to any field on an existing registration and learn about new registrations associated with a business.

This example demonstrates handling an event update triggered by a change in registration status, but the same pattern can be generalized for any field associated with a registration.

**`Ruby`**

```ruby title="Ruby"
require 'json'

# Sinatra
post '/my/monitoring_webhook/url' do
  payload = request.body.read
  event = JSON.parse(payload)

  case event.type
  when 'registration.updated'
    registration_event = event['data']['object']
    business_id = registration_event['business_id']

    # check for presence of a change in status field
		if registration_event['previous_attributes').keys.include('status')
    	puts registration_event['status']
    end
  else
    # Unexpected event type
    status 400
    return
  end

  status 200
end
```

**`Python`**

```python title="Python"
from flask import Flask, request, jsonify

app = Flask(__name__)

# Flask
@app.route('/my/monitoring_webhook/url', methods=['POST'])
def monitoring_webhook():
    payload = request.data
    event = request.get_json()

    if event['type'] == 'person.created':
        registration_event = event['data']['object']
        business_id = registration_event['business_id']

        if 'status' in registration_event['previous_attributes'].keys():
          puts registration_event['status']
    else:
        # Unexpected event type
        return '', 400

    return '', 200

if __name__ == '__main__':
    app.run(debug=True)
```

**`JavaScript`**

```javascript title="JavaScript"
const express = require('express');
const app = express();

app.use(express.json()); // Middleware to parse JSON request bodies

// Express route
app.post('/my/monitoring_webhook/url', (req, res) => {
    const event = req.body;

    if (event.type === 'registration.updated') {
        const registrationEvent = event.data.object;
        const businessId = registrationEvent.business_id;
      	if (Object.keys(registrationEvent.previous_attributes).includes('status') {
          console.log(registrationEvent['status']);
        }

    } else {
        // Unexpected event type
        return res.sendStatus(400);
    }

    res.sendStatus(200);
});

// Start the Express server
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
    console.log(`Server is running on port ${PORT}`);
});
```

### Use the event payload

The event payload includes a snapshot of the registration associated to the business.
Use the `data.object.status` field inside the webhook payload to read the registration's status directly from the webhook event.

A special `previous_attribute`s field is included in the embedded event object.
This field contains a JSON object with the associated key/value pairs that have changed (and includes the previous values).

**`JSON`**

```json title="JSON"
{
  "object": "registration",
  "id": "87b564c8-fb5d-40m2-9e61-b5b5df902aeb",
  "business_id": "006ecba9-4ec4-4610-8a2a-4ff0bb101e94",
  "name": "My Monitored Business",
  "status": "inactive",
  "sub_status": null,
  "status_details": "Inactive",
  "jurisdiction": "FOREIGN",
  "entity_type": "UNKNOWN",
  "file_number": "06717223",
  "addresses": [
    "85 2nd St San Francisco CA, 94105"
  ],
  "officers": [],
  "registered_agent": {},
  "registration_date": "2007-08-21",
  "state": "KY",
  "source": "https://web.sos.ky.gov/BusSearchNProfile/search.aspx",
  "previous_attributes": {
    "status": "active"
  }
}
```

### Use business review tasks

Re-evaluate the business's review tasks by requesting the full business payload using the [GET /businesses endpoint](/api-reference/business-verification/businesses/retrieve-a-business).

Use the [SOS Domestic review task](/reference/business-review-tasks#sos-domestic-review-task-outcomes) to re-evaluate the domestic filing status of the business after receiving the `registration.updated` event.

**`Ruby`**

```ruby title="Ruby"
require 'net/http'
require 'net/https'
require 'json'

def send_request
	business_id = "<business_id>"
  uri = URI("https://api.middesk.com/v1/businesses/#{business_id}")

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Accept", "application/json"
  # Add headers
  req.add_field "Authorization", "Basic <api_key>"

  # Fetch Request
  res = http.request(req)

	response = JSON.parse(res.body)
	sos_domestic_task = response['review']['tasks'].find { |task| task['category'] == 'sos_domestic' }

	if sos_domestic_task['status'] == 'success'
		puts 'SOS status active'
	else
    puts 'SOS status inactive'
	end
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
```

**`Python`**

```python title="Python"
import requests
from requests.auth import HTTPBasicAuth

def send_request():
    business_id = "<business_id>"
    url = f"https://api.middesk.com/v1/businesses/{business_id}"

    headers = {
        "Accept": "application/json",
        "Authorization": "Basic <api_key>"
    }

    try:
        # Make the request
        response = requests.get(url, headers=headers, auth=HTTPBasicAuth('<api_key>', ''))

        # Parse the response JSON
        response_data = response.json()
        sos_domestic_task = next((task for task in response_data['review']['tasks'] if task['category'] == 'sos_domestic'), None)

        if sos_domestic_task and sos_domestic_task['status'] == 'success':
            print('Name match')
        else:
            print('Name match failure')

    except requests.exceptions.RequestException as e:
        print(f"HTTP Request failed ({e})")

send_request()
```

**`JavaScript`**

```javascript title="JavaScript"
  const businessId = "<business_id>";
  const url = `https://api.middesk.com/v1/businesses/${businessId}`;

  const headers = {
    "Accept": "application/json",
    "Authorization": "Basic <api_key>"
  };

  try {
    // Make the request using fetch
    const response = await fetch(url, { headers });

    // Check if the request was successful
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }

    const responseData = await response.json();
    const sosDomesticTask = responseData.review.tasks.find(task => task.category === 'sos_domestic');

    if (personTask && personTask.status === 'success') {
      console.log('SOS status active');
    } else {
      console.log('SOS status inactive');
    }
   catch (error) {
    console.error(`HTTP Request failed: ${error.message}`);
  }
}

sendRequest();
```

### Handle state-specific alerts

The most recent snapshot of the registration is included in the `registration.updated event`.
Use this snapshot to selectively handle webhook events. For example, if you're only interested in events emanating from a specific registration state, ignore events triggered from other registration updates.

This example filters on KY-only updates.

**`Ruby`**

```ruby title="Ruby"
require 'json'

# Only handle updates in KY
post '/my/monitoring_webhook/url' do
  payload = request.body.read
  event = JSON.parse(payload)

  case event.type
  when 'registration.updated'
    registration_event = event['data']['object']
    business_id = registration_event['business_id']
		state = registration_event['state']

		# ignore other states
    return if state != 'KY'

    puts registration_event['status']
  else
    # Unexpected event type
    status 400
    return
  end

  status 200
end
```

Next, use [GET /businesses endpoint](/api-reference/business-verification/businesses/retrieve-a-business) to fetch the full registration payload and select for individual registrations.

**`Ruby`**

```ruby title="Ruby"
require 'net/http'
require 'net/https'
require 'json'

def send_request
	business_id = "<business_id>"
  uri = URI("https://api.middesk.com/v1/businesses/#{business_id}")

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Accept", "application/json"
  # Add headers
  req.add_field "Authorization", "Basic <api_key>"

  # Fetch Request
  res = http.request(req)

	response = JSON.parse(res.body)
	ky_registration = response['registrations'].find {|registration| registration['state'] = 'KY' }

	if ky_registration
		puts 'KY registration"
	else
    puts 'Missing KY registration'
	end
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
```

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