Receive event notifications with webhooks

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

Full payload
Descriptions of all JSON fields for an event
Score change event
Issues event
Security breach event

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:

{
  "trigger": {
    "type": "new_issues",
    "issues": {
      "csp_no_policy_v2": {
        "active": {
          "count": 26
        },
        "departed": {
          "count": 3
        },
        "resolved": {
          "count": 2
        }
      },
      "domain_missing_https_v2": {
        "active": {
          "count": 15
        }
      }
    },
    "selected": "by_severity",
    "severity": "low"
  },
  "created_at": "2022-08-10T19:49:46.029Z",
  "execution_id": "ee08b90e-98fe-45e1-9261-91eb0a80275d",
  "scorecard_id": "8e21f4aa-ee49-5f6d-be70-366b95ecc586",
  "domain": "example.com"
}

Descriptions of all JSON fields for an event

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

Field	Description
`trigger`	Container for all the contextual information about the event
`trigger.type`	Type of the event, which maps to the creation of the related rule
`context.issues`	Container the specific details of the event (Issues list)
`trigger.selected`	Event that triggered Rule
`trigger.severity`	Logic to compare in the Event occurrence
`created_at`	Date of web-hook creation
`execution_id`	UUID for execution
`scorecard_id`	UUID of the Scorecard related to the Event
`domain`	Domain of the Scorecard related to the Event

Score change event

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

{
  "trigger": {
    "type": "grade_drop",
    "score": 54
  },
  "created_at": "2022-08-09T14:47:13.017Z",
  "execution_id": "113666f9-4de5-4770-a172-b7dc89fb01a8",
  "scorecard_id": "8e21f4aa-ee49-5f6d-be70-366b95ecc586",
  "domain": "example.com"
}

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.

{
  "trigger": {
    "type": "new_issues",
    "issues": {
      "csp_no_policy_v2": {
        "active": {
          "count": 26
        },
        "departed": {
          "count": 3
        },
        "resolved": {
          "count": 2
        }
      },
      "domain_missing_https_v2": {
        "active": {
          "count": 15
        }
      }
    },
    "selected": "by_severity",
    "severity": "low"
  },
  "created_at": "2022-08-10T19:49:46.029Z",
  "execution_id": "ee08b90e-98fe-45e1-9261-91eb0a80275d",
  "scorecard_id": "8e21f4aa-ee49-5f6d-be70-366b95ecc586",
  "domain": "example.com"
}

Security breach event

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

{
  "trigger": {
    "type": "breach_reported",
    "breach": {
      "domain": "example.com",
      "root_cause": "hacked",
      "company_name": "Example Company",
      "records_lost": 10000,
      "date_discovered": 0,
      "type_of_breach": "",
      "description": "Company was breached, exposing authentication details of senior employees. An insider is believed to have helped."
    }
  },
  "created_at": "2022-08-09T16:36:42.397Z",
  "execution_id": "87b786f3-76c9-4a2e-a44b-985be679ef80",
  "scorecard_id": "8e21f4aa-ee49-5f6d-be70-366b95ecc586",
  "domain": "example.com"
}

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.