Monitor business activity

How Monitoring works

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

Learn the monitoring lifecycle

Lifecycle of a business with monitoring enabled

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

  1. A business gets created with the POST /businesses endpoint.
  1. The business is subscribed to monitoring.
  2. At some point in the future, a change to that business is detected. The business record updates.
  3. A webhook event is sent to registered webhook endpoint(s).
  4. The client application ingests and evaluates the change in the business record.

Monitor businesses

1

Subscribe a business

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

Use the POST /monitor API to create, update, and delete business monitors for fine-grained control within your application.

2

Set up and listen for monitoring webhook events

Depending on the type of monitor that you want to listen for, register a new webhook with the corresponding event types selected.

3

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.

    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.

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), 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 using the GET /businesses endpoint.

    The response includes the full business record.

Get a demo
Contact your account manager or contact sales to inquire about access.