Monitor status | Middesk

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.

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

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

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

Use the SOS Domestic review task to re-evaluate the domestic filing status of the business after receiving the registration.updated event.

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

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

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 to fetch the full registration payload and select for individual registrations.

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 to inquire about access.