SecurityScorecard

Develop on the SecurityScorecard Platform!

Use our platform’s issue detection, data-driven metrics, and easy-to-read scoring system to measure your cyber-risk against 10 factors and drive smart decisions about how to improve your security posture.


     Build apps      Build integrations

Notify security teams immediately about important security events.

Automate rule-based workflows for fast, repeatable issue response.

In Integrate360° Marketplace, let users pair your solution with SecurityScorecard and many other apps, platforms, and services.

Use the Ratings API to pull our data into a SOC, BI tools, or any reporting or GRC system you use.

Customize and display data in dashboards, reports, or other formats and platforms that support your daily operations.

Automate actions that will help your team respond faster to security events.

Receive event notifications with webhooks

Set up Rules that use webhooks to implement custom behavior in reaction to events on your account or scorecards you monitor

SecurityScorecard Rules let you trigger simple workflows in reaction to different events affecting your account, including changes to the Scorecards you monitor.

When to use a webhook

They are ideal for integrations where:

  • You want to react to any type of scorecard changes, without having to continuously fetch and compare scorecard data, so you can avoid unnecessary polling.
  • You want to include custom logic in the workflow for a rule.
  • You want to connect events in SecurityScorecard with workflows in other tools or infrastructure in your organization.

Sending a web request as part of a rule

When configuring a rule, you can send a web request to a webhook, so allowing you to implement a custom integration in response to the rule's triggering event.

Event examples

Every time an event triggers a rule, an HTTP POST sends details on the event to your endpoint as a JSON body.

Full payload

The following is an example is a payload that includes all event types:

{
  "context": {
    "execution_id": "c3a5b1a7-06f8-484d-aba8-506242caa6bc",
    "event": {
      "type": "scorecard.changed",
      "payload": {
        "domain": "example.com",
        "platform_score_date": 1632315625,
        "previous": {
          "score": 90,
          "factors": {
    // only with changes
            "network_security": 80,
            "dns_health": 95,
            "endpoint_security": 88,
            "patching_cadence": 85
          }
        },
        "current": {
          "score": 10,
          "factors": {
           // only
            "network_security": 80,
            "dns_health": 95,
            "endpoint_security": 88,
            "patching_cadence": 85
          }
        },
        "issues": {
    // only with changes
          "csp_no_policy_v2": {
            "active": {
              "count": 16
            },
            "departed": {
              "count": 3
            },
            "resolved": {
              "count": 2
            }
          },
          "domain_missing_https_v2": {
            "active": {
              "count": 5
            }
          }
        },
        "breach": {
          "root_cause": "hacked",
          "records_lost": 10000,
          "date_discovered": 0,
          "type_of_breach": ""
        },
        "scorecard_id": "eb6106fd-8a37-5395-b3f7-7cb93195fdba"
      }
    },
    "subscription_id": "d1088cb7-3207-4a67-9459-59da92ea4a6a",
    "workflow": {
      // name of the rule
      "name": "Send telegram",
      "filters": {
        "changes": {
          "grade": {
            "value": "any"
          },
         // 
          "value": "grade_drop"
        },
        "scorecards": {
          "value": "in_portfolio",
          "portfolio_id": {
            "value": "5ece90e5b979990018de98f9"
          }
        }
      }
    },
    "created_at": "2021-09-22T13:03:13.219Z",
    "trigger": {
      // trigger type
      "type": "grade_drop",
      "score": 10
    }
  }
}

Descriptions of all JSON fields for an event

See the following table for descriptions of the fields in the JSON body:

Field

Description

context

Container for all the contextual information about the event

context.type

Type of the event, which maps to the creation of the related rule

context.payload

Container the specific details of the event

context.domain

Domain or scorecard where the event occurred

context.payload.platform_score_date

Timestamp for the date when this change occurred

context.payload.previous

Container for overall Scorecard and factor scores prior to the event

context.payload.previous.score

Overall Scorecard score prior to the event

context.payload.previous.factors

For each factor score that was changed by the event, the score of the factor prior to the event.

context.payload.current

Container for overall Scorecard and factor scores after the event

context.payload.current.score

Overall Scorecard score after the event

context.payload.current.factors

For each factor score that was changed by the event, the score of the factor after to the event

context.payload.issues

Newly found issues in the Scorecard as of the event occurrence, including their current status and number of findings

context.payload.breach

If the event is a breach, the details of the breach

context.payload.scorecard_id

Unique identifier for the Scorecard

workflow

Container for details about the action triggered by the rule

workflow.name

Name of the created rule, matched against the action declared in the app manifest

workflow.trigger.type

The reason the action was executed

Score change event

This type of event is emitted whenever a Scorecard score rises or falls.

{
  "context": {
    "execution_id": "c3a5b1a7-06f8-484d-aba8-506242caa6bc",
    "event": {
      "type": "scorecard.changed",
      "payload": {
        "domain": "example.com",
        "platform_score_date": 1632315625,
        "previous": {
          "score": 90,
          "factors": {
            "network_security": 80,
            "dns_health": 95,
            "endpoint_security": 88,
            "patching_cadence": 85
          }
        },
        "current": {
          "score": 80,
          "factors": {
            "network_security": 80,
            "dns_health": 95,
            "endpoint_security": 88,
            "patching_cadence": 85
          }
        },
        "scorecard_id": "eb6106fd-8a37-5395-b3f7-7cb93195fdba"
      }
    },
    "subscription_id": "d1088cb7-3207-4a67-9459-59da92ea4a6a",
    "workflow": {
      "name": "Send telegram",
      "filters": {
        "changes": {
          "grade": {
            "value": "any"
          },
          "value": "grade_drop"
        },
        "scorecards": {
          "value": "in_portfolio",
          "portfolio_id": {
            "value": "5ece90e5b979990018de98f9"
          }
        }
      }
    },
    "created_at": "2021-09-22T13:03:13.219Z",
    "trigger": {
      "type": "grade_drop",
      "score": 10
    }
  }
}

Issues event

This event is emitted when new issues are found in a Scorecard, or if existing issues have changes in status. For example, if an active issue becomes resolved or decayed, this change would generate an event.

{
  "context": {
    "execution_id": "c3a5b1a7-06f8-484d-aba8-506242caa6bc",
    "event": {
      "type": "scorecard.changed",
      "payload": {
        "domain": "example.com",
        "platform_score_date": 1632315625,
        "issues": {
          "csp_no_policy_v2": {
            "active": {
              "count": 16
            },
            "departed": {
              "count": 3
            },
            "resolved": {
              "count": 2
            }
          },
          "domain_missing_https_v2": {
            "active": {
              "count": 5
            }
          }
        },
        "scorecard_id": "eb6106fd-8a37-5395-b3f7-7cb93195fdba"
      }
    },
    "subscription_id": "d1088cb7-3207-4a67-9459-59da92ea4a6a",
    "workflow": {
      // name of the rule
      "name": "Send telegram",
      "filters": {
        "changes": {
          "grade": {
            "value": "any"
          },
         // 
          "value": "grade_drop"
        },
        "scorecards": {
          "value": "in_portfolio",
          "portfolio_id": {
            "value": "5ece90e5b979990018de98f9"
          }
        }
      }
    },
    "created_at": "2021-09-22T13:03:13.219Z",
    "trigger": {
      // trigger type
      "type": "new_issues",
      "score": 10
    }
  }
}

Security breach event

This event is emitted when a new security breach is detected for a Scorecard.

{
  "context": {
    "execution_id": "c3a5b1a7-06f8-484d-aba8-506242caa6bc",
    "event": {
      "type": "scorecard.changed",
      "payload": {
        "domain": "example.com",
        "platform_score_date": 1632315625,
        "breach": {
          "root_cause": "hacked",
          "records_lost": 10000,
          "date_discovered": 0,
          "type_of_breach": ""
        },
        "scorecard_id": "eb6106fd-8a37-5395-b3f7-7cb93195fdba"
      }
    },
    "subscription_id": "d1088cb7-3207-4a67-9459-59da92ea4a6a",
    "workflow": {
      "name": "Send telegram",
      "filters": {
        "changes": {
          "grade": {
            "value": "any"
          },
          "value": "grade_drop"
        },
        "scorecards": {
          "value": "in_portfolio",
          "portfolio_id": {
            "value": "5ece90e5b979990018de98f9"
          }
        }
      }
    },
    "created_at": "2021-09-22T13:03:13.219Z",
    "trigger": {
      "type": "grade_drop",
      "score": 10
    }
  }
}

IMPORTANT: The schema of this payload is in beta and subject to change at any time. After the beta period, we will indicate here that it is stable, so can follow the same backward-compatibility rules established for the rest of our API.

Requirements and limitations for your server

  • Use HTTPS protocol.
  • Accept an HTTP POST with a JSON payload.
  • Respond within five seconds.
  • Respond with a 2xx status.
  • Provide no response body, or a response body smaller than 100 KB.

Errors and retry support

On network errors or an http status 5xx, we will perform a series of retries every 6 hours for up to 36 hours.

NOTE: We MAY limit this further depending on the responsiveness of your integration.

Using a webhook to conditionally stop a workflow

You can optionally implement custom logic in your webhook to conditionally stop the execution of the rule workflow by including in the JSON response a workflowExit property as in the following example:

{
  "workflowExit": true
}

Next steps will be skipped. So this is ideal to implement steps like "Only execute the next steps if ..."

Authentication

We currently do not support custom headers, but it is possible to specify a token as part of the webhook URL query string. We will only perform this requests over an HTTPS connection. We may implement additional mechanisms to secure webhook requests in the future.

Updated 5 months ago


Receive event notifications with webhooks


Set up Rules that use webhooks to implement custom behavior in reaction to events on your account or scorecards you monitor

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.