(Deprecated) Payload Checks

❗️

Payload checks are deprecated!

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. However, not all checks fall perfectly in line with one of the pre-built checks provided by OpsLevel. With payload checks, you can easily create custom, data driven checks and format the result messages to provide the context you want. These checks allow you to evaluate various conditions by sending any JSON payload directly to OpsLevel.

The following are examples of conditions you can easily evaluate using these checks:

• Using your vulnerability detection tool to ensure that no Tier
• 1 services have open vulnerabilities.
• Using your vulnerability detection tool to ensure no Ruby services have high criticality vulnerabilities.
• Ensuring your test coverage stays above a certain threshold.

You could implement examples like the above with Custom Checks, but Payload Checks make specifying thresholds significantly easier.

Getting Started with Payload Checks

Create a Payload Check Integration

1. To set up a payload check endpoint, visit the Integrations tab and select "New Integration", followed by Payload.
2. Click + Add Integration on the Payload Integration card and then New Payload Integration
3. After creating a Payload Integration, you'll be redirected to a page that looks like:

Create a Payload Check

Payload checks are a type of check that allow you to send arbitrary JSON payloads to an OpsLevel endpoint. You can evaluate that payload against a jq expression and return a custom check result message using Liquid templating.

1. Navigate to the Rubrics sub menu under the Service Maturity menu in OpsLevel
2. Hover over the cell that corresponds to the level and category you want your check to live in and click the + Add Check button.
3. Create a Payload Check.
4. Fill out the check information and press Create.

You can enter a jq Expression which will be run against the input check payload to determine if the check is passing or failing. Refer to the jq Expressions section for more information and some examples.

You can enter a Result Message to provide a custom check result message which supports both Markdown and Liquid templating. For more information and some examples, refer to the Liquid Templating section.

In the Test Check section, you can test out your check before releasing it into the wild. You can enter a sample JSON payload that the jq Expression will be evaluated against. Then the Result Message will be evaluated and you can see the final result in the Test Result.

Sending a JSON Payload to OpsLevel

It is easy to start sending payloads for a payload 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** if you haven't send a payload to that check for the specific service.

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

POST https://app.opslevel.com/integrations/payload/xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx
HTTP/1.1
Content-Type: application/json
{
  "service": "shopping_cart",
  "check": "checkIdentifier",
  "data": {
    "_comment": "YOUR DATA HERE"
  }
}

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:

Handling Errors

The Payload check API may throw errors when receiving malformed requests, when utilizing endpoints that are no longer valid, or when we're too busy trying to determine who the werewolf is among us to route your webhooks correctly.

In such cases, payload 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

jq Expressions

Example: Check for Vulnerabilities on Your Service's Repositories with Snyk

When using Snyk, you may want to ensure that the repos used by your service have no high criticality security vulnerabilities.

You can use Snyk's API to fetch vulnerability counts.

Send a POST request to the following Snyk API Endpoint: <https://snyk.io/api/v1/reporting/counts/issues/latest?groupBy=severity>

You will receive a response similar to:

{
  "results": [    
    {      
      "day": "2017-07-01",      
      "count": 13,      
      "severity": {        
        "high": 0,        
        "medium": 4,        
        "low": 9      
      }    
    }  
  ]
}

Forward this to OpsLevel's payload check endpoint.

For a full example, do the following.

1. Get an API token and Organization ID
2. Set up the following environment variables:
   bash

   SNYK_TOKEN=<Snyk API Token>
   SNYK_ORGANIZATION=<Snyk Organization ID>
   OPSLEVEL_SERVICE_ALIAS=<OpsLevel Service Alias>
   OPSLEVEL_CHECK_ID=<OpsLevel Check ID>
   OPSLEVEL_PAYLOAD_URL_TOKEN=<OpsLevel Payload URL Token>
   

3. Run the following command:
   bash

   curl --X POST 'https://snyk.io/api/v1/reporting/counts/issues/latest?groupBy=severity'
   \--H 'Content-Type: application/json' 
   \--H 'Authorization: '"$SNYK\_TOKEN"'' 
   \--data-raw '{    
     "filters": {        
       "orgs": ["'"$SNYK_ORGANIZATION"'"]    
     }
   } | curl -X POST 'http://app.opslevel.com/integrations/payload/${OPSLEVEL_PAYLOAD_URL_TOKEN'
   \-H 'content-type: application/json' 
   \-d '{
     "service": "'$OPSLEVEL_SERVICE_ALIAS'",
     "check": "'$OPSLEVEL\_CHECK\_ID'",  
     "data": '$(\</dev/stdin)'
   }'
   

Example: Check for Correct API Version on Kubernetes Deploy

In this example we will be using an example service called cartservice.

If you use Kubernetes and wish to check if you are using the correct API version on deploy, you can run the following command:

kubectl get deployment cartservice -o json

The resulting JSON payload can be forwarded to OpsLevel to run Payload Checks against.

The payload will look similar to:

{
  "apiVersion": "apps/v1",
  "kind": "Deployment",
  # ...
  "status": {
    "availableReplicas": 1,
     # ...
  }
}

jq Error Messages

When creating a payload check, you may experience one of the following jq related error messages.

Liquid Templating

Payload checks allow you to use Markdown combined with Liquid Templates templating to create your own custom result messages.

Liquid Template Variables

When creating custom result messages with Liquid, OpsLevel gives you access to some variables to use in the Liquid template.