SecurityScorecard

SecurityScorecard Developer Hub

Integrate with the world’s most comprehensive source of cybersecurity data using SecurityScorecard's APIs.

Get Started    API Reference

Receive event notifications with webhooks

Setup 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 on 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 (avoid unnecessary polling)
  • you want to include custom logic in the workflow on 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 Rules

At one of the Rule steps you can send a web request to a webhook allowing you to implement a custom integration in response to these events.

Every time this rule is triggered, an http POST will send details on the event to your endpoint as a JSON body. Here's an example payload:

{
  "created_at": "2020-12-04T10:00:35.194Z",
  "scorecard_id": "2d2e6c04-4859-5031-b3bc-6d7fa9762be4",
  "domain": "example.com",
  "trigger": {
    "type": "grade_drop",
    "score": 82
  }
}

IMPORTANT: The schema of this payload is still unstable and it's subject to change at any time after a beta period we'll identify it as stable here, at which point would follow the same backward compatibility rules established for the rest of our API.

Requirements & Limitations for your server

  • use https protocol
  • accept an http POST with a json payload
  • respond within 5 seconds
  • respond with a 2xx status
  • no response body, or a response body smaller than 100KB

Errors and Retry support

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

Note: we might 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 sto the execution of the Rule workflow by including in the JSON response a workflowExit property as in the example below:

{
  "workflowExit": true
}

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

Authentication

At the moment, we don't support custom headers but it's possible to specify a token as part of the webhook url query string. We will only perform this requests over an https connection. We might implement additional mechanisms to secure webhook requests in the future.

Updated 6 months ago


Receive event notifications with webhooks


Setup 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.