> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SecurityScorecard alert integration

> Send SecurityScorecard score changes, new issues and breach events to Flashduty On-call with the Rule Builder Send a web request action.

Use the **Send a web request** action of a SecurityScorecard Rule Builder rule to send Scorecard events to Flashduty On-call. Each time the rule runs, SecurityScorecard sends one POST request, and Flashduty creates one alert for it.

SecurityScorecard sends an event once, when it happens, and sends no recovery notification, so these alerts do not recover on their own. Turn on the auto-resolve timeout in the channel, as described in [Alerts do not recover](#alerts-do-not-recover).

<div className="hide">
  ## In Flashduty On-call

  ***

  You can obtain an integration push URL in either of the following ways.

  ### Use a dedicated integration

  1. In the Flashduty console, select **Channel** and open a channel
  2. Select **Settings** → **Integrations** → **Dedicated integrations**, then click **Add an integration**
  3. Select **SecurityScorecard** and click **Save**
  4. Open the generated integration card and copy the **Push URL**

  ### Use a shared integration

  1. In the Flashduty console, go to **Integration Center → Alert events**
  2. Select **SecurityScorecard** and enter an integration name
  3. Configure the default route and choose a channel. You can add more rules under **Routes** after the integration is created
  4. Click **Save** and copy the generated **Push URL**
</div>

## Configure SecurityScorecard

***

Rule Builder requires a paid SecurityScorecard plan, and each user can create up to 25 rules.

<Steps>
  <Step title="Create a rule">
    1. Sign in to the SecurityScorecard platform, go to **Automation** → **Rule Builder**, and click **Create Rule** (in the older interface: avatar in the upper-right corner → **My Settings** → **Rules**)
    2. Select **Events** so the rule runs when an event occurs
    3. Enter a rule name, for example `Flashduty: vendor score drop`
    4. Choose the Scorecards the rule monitors: your organization's Scorecard, a single Scorecard, or a portfolio
    5. Choose the triggering event, for example the overall score dropping below a threshold, a new issue of a given severity, or a reported breach
  </Step>

  <Step title="Add the Send a web request action">
    1. Select **Send a web request** as the action
    2. Paste the full Flashduty push URL, including the `integration_key` parameter, as the URL. SecurityScorecard only sends to HTTPS URLs and does not support custom headers, so `integration_key` must stay in the URL
    3. Review the rule and click **Save**

    From then on, every run of the rule sends one POST to that URL with a JSON body containing `trigger`, `execution_id`, `scorecard_id` and `domain`.
  </Step>

  <Step title="Verify">
    Rule Builder has no button that sends a test request. SecurityScorecard evaluates Scorecard events once a day, and the rule runs after an event meets its conditions. To verify right away, simulate an event with the SecurityScorecard API [Simulate Actions](https://securityscorecard.readme.io/docs/simulate-actions) (include the rule's `rule_id` in the request) and check that the alert arrives in Flashduty. The simulation creates a real alert; close it by hand afterwards.
  </Step>
</Steps>

## Alert Key

***

Flashduty computes the Alert Key from `execution_id`, `scorecard_id` and `trigger.type`. The SecurityScorecard article [Rule Builder: Webhooks](https://support.securityscorecard.com/hc/en-us/articles/360058429271-Rule-Builder-Webhooks) defines `execution_id` as the unique identifier of one rule execution, and it stays the same when a failed request is retried. A retry of the same execution therefore merges into the same alert, and every other rule execution becomes its own alert.

When a request has no `execution_id`, Flashduty generates a random Alert Key and every request becomes a new alert. A request without `trigger.type` returns a parameter error.

## Severity

***

| Event (`trigger.type`) | Condition | Flashduty severity |
| :- | :- | :- |
| Breach (`breach_reported`) | | Critical |
| New issues (`new_issues`) | `trigger.severity` is `high` or `critical` | Critical |
| New issues (`new_issues`) | `trigger.severity` is `medium`, absent or an unrecognized value | Warning |
| New issues (`new_issues`) | `trigger.severity` is `low`, `info` or `informational` | Info |
| Score change (`grade_drop`) and any other event type | | Warning |

## Field mapping

***

| Flashduty | SecurityScorecard field |
| :- | :- |
| Title | Event type and `domain` (`scorecard_id` when `domain` is absent), for example `SecurityScorecard score change: example.com (score 54)`, `SecurityScorecard new issues: example.com (2 issue types)`, `SecurityScorecard breach reported: example.com`; other event types read `SecurityScorecard <trigger.type>: <domain>` |
| Description | Event type, `domain`, `trigger.score`, `trigger.severity`, the active / departed / resolved count of each issue type, and the breach description |
| Labels | `trigger_type` (also as `check`), `domain` (also as `resource`), `scorecard_id`, `execution_id`, `score`, `selected`, `issue_severity`, `issue_types`, and for breach events `breach_root_cause`, `breach_company`, `breach_records_lost`, `breach_type` |

The `retries` and `webhooks` (responses of earlier webhooks in the rule) fields are not copied to the alert. SecurityScorecard marks this request body as beta; if the structure of the issue or breach details changes, Flashduty ignores the parts it cannot parse and still creates the alert.

## Alerts do not recover

***

Score changes, new issues and breaches are one-shot events, and SecurityScorecard sends no recovery notification. Turn on [auto-resolve timeout](/en/on-call/channel/create-edit) in the channel that receives this integration. 24 hours is a reasonable start; adjust it to how long your team takes to handle security rating events.

## Troubleshooting

***

<AccordionGroup>
  <Accordion title="The rule ran but no alert arrives">
    Check that the rule action is **Send a web request** and the URL is the full push URL starting with `https://`. SecurityScorecard evaluates events once a day, so a rule does not run at the moment a Scorecard changes. A score rule fires only when the change is greater than the configured value, not equal to it.
  </Accordion>

  <Accordion title="You receive an [Action Required] Failed Webhook Request email">
    SecurityScorecard retries on network errors and 5xx responses and emails the rule owner when the request still fails after 36 hours. Check that the push URL is complete and that the integration has not been deleted.
  </Accordion>

  <Accordion title="Flashduty returns a parameter error">
    The request body must be JSON of at most 1 MiB with a non-empty `trigger.type`, and the `integration_key` in the push URL must belong to a SecurityScorecard integration.
  </Accordion>
</AccordionGroup>

For the meaning of every field, see [Receive event notifications with webhooks](https://securityscorecard.readme.io/docs/receive-event-notifications-with-webhooks) in the SecurityScorecard docs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.