Custom Checks

Deprecation Note: It’s recommended to use the newer, more flexible Custom Event Check.

OpsLevel helps keep your services consistent and mature through the use of various pre-built checks.

But what if you want to write your own checks from scratch? You can now do that with OpsLevel custom checks. Our custom checks API opens up endless possibilities, allowing you to do things such as integrating with your deployment pipeline or container orchestrator, writing your own check scripts, and more.

Getting Started with Custom Checks

Creating a Check Integration (If you deleted the default integration)

All OpsLevel accounts come preconfigured with a Check Integration. If you have no Check Integration, perform the following steps.

To set up a check webhook, visit our Integrations tab and select “New Integration”, followed by Check. (Note that if you don’t have any integrations, you’ll be shown the new integration page directly).

Click “+ Add Integration” on the Check integration card and then “New Check Integration”:

After creating a check integration, you’ll be redirected to a page that looks like:

Creating a Custom Check

Custom checks are a type of check that allow you to update their status through the check integration.

To create a custom check, navigate to the Checklists tab.

If you already have checklists created, you will see them here. If not, visit our Checklists page to learn more about checks.

For the purpose of this guide, we will be using our All Services checklists.

Navigate to the checklist you wish to create a check for.

Press the “+ Add Check” button.

From the Create Check modal, select Custom Check from the Type dropdown:

Fill out the check information and press Create:

After successfully creating a check, you will see it in the Checks card.

Finding the Check Identifier

The check reference ID is required in the payload you send via our api to determine which custom check your check result belongs to.

To find the check reference ID, navigate to the Checklist page.

Navigate to the checklist your Custom Check belongs to.

The Check Identifier will appear as shown below for your Custom Check:

Adding Results of a Custom Check to a Service via API

It is easy to start adding results for a custom check to a particular service in OpsLevel. Begin by navigating to the check result by visiting the Scorecards tab of your service. Hint: the check result will be yellow.

Using the Custom Check Identifier and Service Alias provided, make an HTTP POST request like the example below, substituting your Webhook URL in place of xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx:

POST http://app.opslevel.com/integrations/check/xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/1.1
Content-Type: application/json

{
  "service": "shopping_cart",
  "check": "checkIdentifier",
  "status": "passed",
  "message": "You shall pass!!!!"
}

If your webhook was successful, you will receive the following response:

{
  "result": "ok"
}

Here is a full explanation of all the fields in the json object:

If a message longer than 4096 characters is sent it will be truncated and a warnings field will be included in the response:

{
    "result": "ok",
    "warnings": {
        "message": [
            "was truncated because it exceeded 4096 characters"
        ]
    }
}

Handling Errors

Custom check webhooks may throw errors when receiving malformed requests, when utilizing webhook URLs that are no longer valid, or when we’re too busy trekking to Mordor to press the right buttons.

In such cases, check webhooks return verbose and descriptive errors.

An example of such error:

{
  "errors": [
    {
      "status": 422,
      "title": "No service found with alias 'invalid_alias'.",
      "detail": null
    }
  ]
}

The error above notifies the user that even though we received the webhook payload, the service provided was not found in your OpsLevel account.

Common Errors

If you are having trouble creating or updating custom checks in any way, send us an email at support@opslevel.com and we’ll help you get set up.