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

# GitGuardian alert integration

> Send triggered, updated, and closed secret-leak incidents from GitGuardian to Flashduty On-call through a Custom webhook.

Use the Custom webhook destination of GitGuardian to send secret-leak incidents to Flashduty On-call. Each GitGuardian incident maps to one Flashduty alert: a newly detected incident, a new occurrence, a change in severity or validity, or a reopened incident triggers or updates that alert, and the alert recovers when the incident is marked resolved or ignored.

<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 **Configuration** → **Integrations** → **Private integration**, then click **Add an integration**
  3. Select **GitGuardian**, then click **Save**
  4. Open the generated integration card and copy the **Push URL**

  ### Use a shared integration

  1. In the Flashduty console, select **Integration Center → Alert Events**
  2. Select **GitGuardian** and enter an integration name
  3. Configure the default route and select a channel; after creation, add more rules under **Route** if needed
  4. Click **Save** and copy the generated **Push URL**
</div>

## Configure GitGuardian

***

You need permission to manage integrations in the GitGuardian workspace.

<Steps>
  <Step title="Create a Custom webhook">
    1. In the GitGuardian dashboard, go to **Settings → Integrations → Destinations → Custom webhook**
    2. A webhook belongs to a team. To receive every incident in the workspace, click **Add integration** on the **All-incidents team** row; to receive only one team's incidents, use that team's row
    3. On the **Configuration** tab, paste the complete Flashduty integration Push URL into **Webhook URL** (it must include `integration_key`) and click **Next**

    GitGuardian generates a signature token for the webhook. Flashduty authenticates by the `integration_key` in the Push URL and does not verify the signature, so you do not need to enter the token in Flashduty.
  </Step>

  <Step title="Select events">
    On the **Events** tab, enter an **Events name**, turn on **Internal monitoring**, and under **Notify when** select these events (or click **Select all**):

    | Option in GitGuardian | `action` | Effect in Flashduty |
    | :- | :- | :- |
    | New incident detected | `incident_triggered` | Triggers an alert |
    | Incident has new occurrence | `new_occurrence` | Triggers or updates the alert |
    | Secret validity change | `incident_validity_changed` | Triggers or updates the alert |
    | Incident status change → Severity change | `incident_severity_changed` | Triggers or updates the alert; the severity follows |
    | Risk score updated (Business plan) | `incident_risk_score_updated` | Triggers or updates the alert |
    | Incident regression | `incident_regression` | Triggers or updates the alert |
    | Incident status change → Reopened | `incident_reopened` | Triggers or updates the alert |
    | Incident status change → Resolved | `incident_resolved` | Recovers the alert |
    | Incident status change → Ignored | `incident_ignored` | Recovers the alert |

    <Warning>
      You must select **Resolved** and **Ignored** under **Incident status change**, or the Flashduty alert does not recover when the incident is handled.
    </Warning>

    Assignment, comment, feedback, access, public sharing, and Honeytoken events do not change alert state. Flashduty returns success for them and creates no alert, so you do not need to select them.

    To page only for high-risk leaks, add filtering rules to the webhook by severity, validity, secret type, or tag. Without rules, every incident is sent.
  </Step>

  <Step title="Verify the lifecycle">
    Trigger a new incident in the workspace and confirm that Flashduty receives an active alert. Then mark the incident **Resolved** in GitGuardian and confirm that the alert recovers.

    **Send test message** in the webhook's menu (the three dots on its row) only verifies that the URL is reachable: Flashduty returns success but creates no alert.
  </Step>
</Steps>

## Alert Key

***

Flashduty uses the incident `id` (`incident.id` in the webhook) as the Alert Key. In GitGuardian's published webhook examples, the New incident, New occurrence, Resolved, Ignored, and Reopened events of the same incident carry the same `incident.id`.

Changes to severity, validity, occurrence count, or detector name do not change the Alert Key. Incident events without `incident.id` are rejected.

## Status and severity

***

The alert status follows `action`: `incident_resolved` and `incident_ignored` recover the alert, and every other event in the table above triggers it. A validity, severity, or risk score change on an incident that is already resolved or ignored is ignored and does not re-open the alert. A reopened incident triggers a new alert with the same Alert Key.

The severity follows `incident.severity`:

| GitGuardian severity | Flashduty severity |
| :- | :- |
| `critical`, `high` | Critical |
| `medium` | Warning |
| `low`, `info` | Info |
| `unknown`, empty, or any other value | Warning |

`unknown` means GitGuardian has not rated the incident yet, so Flashduty treats it as Warning.

## Labels

***

| Label | Source |
| :- | :- |
| `incident_id` | Incident ID, which is the Alert Key |
| `incident_url` | Link to the incident in GitGuardian |
| `check` / `detector` | Detector display name / detector name, such as AWS Keys / `aws_iam` |
| `action` | Event type of this delivery |
| `status` | Incident status |
| `severity_raw` | Original GitGuardian severity |
| `validity` | Secret validity: `valid`, `invalid`, `no_checker`, or `not_checked` |
| `occurrence_count` | Number of occurrences |
| `secret_revoked` | Whether the secret has been revoked |
| `team` | GitGuardian team that sent the delivery |
| `repository` / `filepath` / `occurrence_url` | Repository, file path, and link of the new occurrence in `new_occurrence` events |

## Troubleshooting

***

* **No alert was created**: confirm the matching event is selected and that the webhook's filtering rules do not exclude the incident. GitGuardian states that webhook delivery is best effort and not guaranteed
* **The alert did not recover**: confirm **Resolved** and **Ignored** are selected under **Incident status change**
* **Flashduty returns an invalid-parameter error**: confirm the target URL is complete and includes `integration_key`
* **An ignored incident is reopened**: a new alert is created with the same Alert Key

For field details, see [GitGuardian Custom webhook](https://docs.gitguardian.com/platform/configure-alerting/notifiers-integrations/custom-webhook).