> For clean Markdown of this page, append .md to its URL. For the complete documentation index, see https://www.superagent.sh/llms.txt.


Send red-team report, finding, dependency and image validation, contributor trust, and agent monitoring events to your own systems.

# Webhooks

Use **Webhooks** to send repository, application, and Agent red-team report
lifecycle events, findings, Dependency and Image Validation results, contributor
trust, and agent monitoring alerts to your own agents, ticketing systems, and
remediation workflows. Webhooks are configured at the organization level from **Webhooks**
(`/app/webhooks`).

To send these events to Datadog, Grafana Cloud, or an OpenTelemetry Collector,
see [Telemetry](https://www.superagent.sh/docs/telemetry).

## Create a webhook target

1. Open **Webhooks** in the sidebar.
2. Select **Add webhook**.
3. Enter a target name, for example `Remediation agent`.
4. Enter a valid HTTPS URL.
5. Optionally add request headers, for example `Authorization` for an authenticated receiver such as a Cursor automation webhook. Header values are encrypted at rest.
6. Choose the events this target should receive.
7. In the grouped **Sources** dropdown, select one or more entire groups or specific repositories, applications, agents, and images.
8. Save the target and copy the signing secret. The secret is shown only once.

You can create multiple webhook targets for the same organization. New targets subscribe to existing events by default, except infrastructure incident escalation and Image Validation, which require explicit opt-in. Existing targets must opt in to newly added events, including `dependency_validation.finished` and `image_validation.finished`, from their event subscriptions.

## Filter by source

Source filters route events by Security Factory modality:

- **Repositories** includes repository reports, pull request findings, Dependency Validation,
  historical Dependency Updates, Contributor Trust, and GitHub advisories.
- **Applications** includes application reports and findings.
- **Agents** includes Agent red-team and Runtime Guardrails events.
- **Infrastructure** includes security-one incident escalation from connected logs.
- **Images** includes Image Validation results from monitored container repositories.

The Sources dropdown supports multiple selections grouped under Repositories,
Applications, Agents, Infrastructure, and Images. Select an **All** option to include
every current and future source in that group, or select exact persistent
sources. New and existing webhook targets default to all sources.

An event without a persistent source association, such as an organization-wide
Contributor Trust scan or an ad hoc report, is sent only to endpoints that
include all sources in its group. Filters are evaluated when the event is first
enqueued, so retries continue to use the same matched targets.

## Events

| Event | When it fires |
| --- | --- |
| `infrastructure.incident.escalated` | Security-one escalates an infrastructure incident under an enabled monitoring policy. |
| `report.started` | A customer-visible repository, application, or Agent red-team report is created and accepted for provisioning. |
| `report.finished` | The report's agent run completes, enters review, or fails, including provisioning failures. |
| `finding.created` | A repository, application, or Agent red-team report or GitHub advisory creates a new finding. |
| `finding.triage_completed` | Automated triage completes and remediation context is available. |
| `finding.accepted` | A finding is resolved as accepted risk. |
| `dependency_validation.finished` | A Dependency Validation scan finalizes its assessment or fails, including failures before a report is created. |
| `image_validation.finished` | An Image Validation run completes, fails, or is cancelled, with pinned image identities and advisory assessments. |
| `dependency_update.published` | Historical event for a pull request published by the retired dependency updater. |
| `contributor_trust.finished` | An API-started Contributor Trust scan completes or fails. |
| `agent.finding_created` | An endpoint security rule detects agent activity that was not paired with a blocked action. |
| `agent.action_blocked` | Agent monitoring denies an action. A linked finding and enforcement decision produce one event. |

`report.finished` fires once per report. A successful run usually finishes with report status `in_review`; a failed run has `outcome: "failed"`. Retrying the same report does not produce another lifecycle pair. Internal reports used to triage individual findings do not emit report events.

`finding.triage_completed` is the main handoff event for remediation agents. It includes the triage summary, recommendation, evidence, code references, and proposed patch diff when Superagent produced one.

`dependency_update.published` belongs to the retired dependency updater and is
no longer emitted. Dependency Validation emits `dependency_validation.finished`
and publishes GitHub checks and PR comments on supported security pull requests.
Generic `report.started` and `report.finished` events continue to describe the
underlying report lifecycle; they do not include the final PR assessment.

`contributor_trust.finished` is sent to every enabled endpoint in the scan's
organization that subscribes to the event. It fires for both completed and
failed API scans. See the
[Contributor Trust API](https://www.superagent.sh/docs/api/contributor-trust) to start and poll scans.

## Delivery

Superagent sends webhook requests as `POST` requests with a JSON body.

Your endpoint should:

- Return any `2xx` response to acknowledge delivery.
- Be idempotent by event `id`.
- Verify the request signature before processing the payload.
- Respond quickly and do longer work asynchronously in your own system.

Superagent retries network errors, `408`, `429`, and `5xx` responses with backoff.

You can attach custom request headers to every delivery, including test events. Use this for receivers that require an `Authorization` bearer token. Superagent always sets `Content-Type`, `User-Agent`, and the `X-Superagent-*` signature headers, and those names cannot be overridden.

## Payload format

Every webhook uses a versioned envelope. The `data.object` field contains a
report, finding, Dependency or Image Validation assessment, historical dependency
update, Contributor Trust scan, or agent alert.

```json
{
  "id": "evt_...",
  "type": "finding.triage_completed",
  "api_version": "2026-07-08",
  "created_at": "2026-07-08T07:12:00.000Z",
  "organization_id": "org_uuid",
  "data": {
    "object": {
      "id": "finding_uuid",
      "object": "finding",
      "kind": "repository_red_team",
      "title": "SQL injection in search endpoint",
      "repository": "acme/web",
      "risk_level": "high",
      "triage_status": "resolved",
      "triage": {
        "summary": "The endpoint builds SQL using unsanitized input.",
        "recommendation": "Use parameterized queries.",
        "verification_status": "confirmed"
      },
      "remediation": {
        "files": ["app/api/search/route.ts"],
        "patch": {
          "format": "unified_diff",
          "diff": "diff --git ...",
          "truncated": false
        },
        "code_references": []
      }
    }
  }
}
```

### Dependency Validation payload

Subscribe to `dependency_validation.finished` and the **Repositories** source to
act on the final PR assessment. Exact repository filters are supported. Existing
webhook targets must explicitly add this event to their subscriptions.

The event is emitted once per scan, independently of GitHub check/comment
publication. A new scan of the same PR has a new object ID. Deliveries are
idempotent by envelope `id`; retries preserve that ID and payload.

`data.object` contains:

| Field | Meaning |
| --- | --- |
| `id`, `object` | Scan UUID and `"dependency_validation"`. |
| `status` | `completed` or `failed`; completion alone does not mean the fix is verified. |
| `repository` | Persistent repository `id` and GitHub `full_name`. |
| `pull_request` | PR `number` and `url`. |
| `base_sha`, `head_sha` | Exact commits tested; `base_sha` can be null if setup failed before context was saved. |
| `conclusion` | `success`, `failure`, `neutral`, or `cancelled`. |
| `summary` | Public assessment summary. |
| `report` | Report `id` and dashboard `url`, or null if no report was created. |
| `completed_at` | Scan completion timestamp. |
| `advisory_count`, `assessment_count` | Total advisory targets and validated assessments. |
| `assessments`, `assessments_truncated` | Bounded advisory details and whether some assessments were omitted. |

Each assessment includes `advisory_id`, `package`, `ecosystem`, `manifest`,
`old_version`, `new_version`, `exposure`, `fix`, `priority`, `head_healthy`,
`verification_complete`, `reason`, and `impact`. `new_version` is null when the
package was removed. Exposure is `exploitable`, `not_applicable`, or
`inconclusive`; fix is `verified`, `still_exploitable`, `inconclusive`, or
`not_tested`. Priority is `critical`, `high`, `medium`, `low`, or `undetermined`.
`verification_complete` requires a healthy head, a conclusive assessment, and no
recorded verification gaps. It does not override the overall conclusion.

`failure` means an advisory remains exploitable. `neutral` means the result is
inconclusive, incomplete, or the environment/investigation failed; it must never
be treated as proof of a fix. `cancelled` means the comparison was invalidated.
Superseded heads do not enqueue new assessments. Compare `head_sha` with the
current PR head before acting on a delivery.

At most 100 assessments are included, with higher priorities first. Prose and
metadata are bounded to keep deliveries below the payload limit. Use the report
link for full evidence. Reproduction commands, artifacts, repository environment
variables, and runner credentials are not included.

### Image Validation payload

Subscribe to `image_validation.finished` and the **Images** source. Select exact
monitored image repositories to route results to their owners. This event is
excluded from the default subscriptions for both new and existing targets.

The event is emitted when a run first enters `completed`, `failed`, or
`cancelled`. The terminal result and delivery intent are saved together;
delivery retries preserve the event ID and payload without repeating validation
or billing. Subscribe before the run finishes to receive its result.

`data.object` contains:

| Field | Meaning |
| --- | --- |
| `id`, `object` | Run UUID and `"image_validation"`. Use the run UUID with `GET /api/v1/reports/{report_id}`. |
| `repository_id` | Persistent monitored image repository UUID, matched by Images source filters. |
| `status` | `completed`, `failed`, or `cancelled`; completion alone does not establish a verified fix. |
| `image` | Affected image version, including its pinned `digest`, `uri`, and `platform`. |
| `candidate` | Replacement version with the same identity fields, or null for exposure-only validation. |
| `environment_revision` | Test configuration revision pinned when the run was admitted. |
| `result` | Validated assessment result, or null when no result is available. |
| `error` | Failure detail when available, otherwise null. |

The result uses camelCase fields: `digest`, `candidateDigest`, `platform`,
`summary`, optional `userExplanation`, and `assessments`. Each assessment contains
`targetKey`, `exposure`, `fix`, `reason`, `impact`, `baseEvidence`,
`candidateEvidence`, `candidateHealthy`, `verificationGaps`, `limitations`, and
`independentlyVerified`. Evidence entries contain `command`, `observation`, and
an optional `artifact`.

Exposure is `exploitable`, `not_applicable`, or `inconclusive`. Fix is `verified`,
`still_exploitable`, `inconclusive`, or `not_tested`. A verified fix requires
paired exploit evidence, independent verification, a healthy candidate, and no
verification gaps. Without a candidate, fix is `not_tested`. Failed, cancelled,
and inconclusive results must not resolve an advisory automatically.

Before using an event for a deployment decision, compare the pinned image and
candidate digests and environment revision with the intended release. Registry
tags may have moved since the run started. Registry credentials and environment
variable values are not included in the event.

For an end-to-end setup with a signed receiver and remediation workflow, see
[Validate container images with webhooks](https://www.superagent.sh/docs/use-cases/validate-container-images-with-webhooks).

### Report payload

Report events use `object: "report"` and a `type` of `repository`, `web_app`,
or `agent`:

```json
{
  "id": "evt_...",
  "type": "report.finished",
  "api_version": "2026-07-08",
  "created_at": "2026-07-22T07:45:00.000Z",
  "organization_id": "org_uuid",
  "data": {
    "object": {
      "id": "report_uuid",
      "object": "report",
      "type": "repository",
      "repository": "https://github.com/acme/web",
      "trigger_source": "manual",
      "custom_goal_prompt": "Focus on authorization boundaries.",
      "status": "in_review",
      "sandbox_status": "ready",
      "agent_status": "completed",
      "dashboard_url": "https://superagent.sh/app/reports/repository/report_uuid",
      "outcome": "succeeded",
      "error": null,
      "agent_started_at": "2026-07-22T07:01:00.000Z",
      "agent_completed_at": "2026-07-22T07:45:00.000Z",
      "created_at": "2026-07-22T07:00:00.000Z",
      "updated_at": "2026-07-22T07:45:00.000Z"
    }
  }
}
```

For application reports, the object contains `target_url`, `allowed_host`, and
`request_throttle_rpm` instead of repository fields.

For Agent red-team reports, the object includes `agent_id` when the report is
linked to a persistent Agent, plus `description`, `agent_type`, `target_kind`,
`target_url`, `allowed_host`, `request_throttle_rpm`, and `trigger_source`.
Credentials, target headers, API request bodies, sandbox identifiers and
configuration, runner tokens, and encrypted values are never included.

When `outcome` is `failed`, `error` contains a `phase` of `provisioning` or `agent` and a safe error `message`. `report.started` has `outcome: null`, `error: null`, and reflects the report's initial provisioning state.

### Contributor Trust payload

Contributor Trust events use `object: "contributor_trust_scan"`. Completed and
failed scans share the same payload shape:

```json
{
  "id": "evt_...",
  "type": "contributor_trust.finished",
  "api_version": "2026-07-08",
  "created_at": "2026-08-10T12:00:00.000Z",
  "organization_id": "org_uuid",
  "data": {
    "object": {
      "id": "scan_uuid",
      "object": "contributor_trust_scan",
      "login": "octocat",
      "status": "completed",
      "score": 91,
      "score_version": "deterministic-v2.1",
      "verdict": "trusted",
      "confidence": "high",
      "sub_scores": {
        "identity": 92,
        "behavior": 90,
        "content": 91
      },
      "analyzed_pr_count": 10,
      "public_evidence": [
        {
          "repo": "octocat/hello-world",
          "number": 12,
          "title": "Harden request validation",
          "url": "https://github.com/octocat/hello-world/pull/12",
          "verdict": "clean",
          "files_reviewed": ["src/validator.ts"]
        }
      ],
      "error": null,
      "started_at": "2026-08-10T11:58:00.000Z",
      "completed_at": "2026-08-10T12:00:00.000Z",
      "created_at": "2026-08-10T11:58:00.000Z",
      "updated_at": "2026-08-10T12:00:00.000Z"
    }
  }
}
```

For failed scans, `status` is `failed`, score fields are `null`, and
`error.message` contains a safe failure summary. Private repository names,
private pull request identifiers, patches, signals, threats, and free-form agent
evidence are not included. Public evidence is limited to GitHub source metadata
and reviewed file names. Delivery uses the same signatures and retry policy as
every other event.

### Dependency update payload

The `dependency_update.published` event belongs to the retired updater. New Dependency Validation results are published as GitHub checks and PR comments; this legacy event is no longer emitted.

Historical dependency update events use `object: "dependency_update"` and include
the published pull request:

```json
{
  "id": "evt_...",
  "type": "dependency_update.published",
  "api_version": "2026-07-08",
  "created_at": "2026-09-18T07:00:00.000Z",
  "organization_id": "org_uuid",
  "data": {
    "object": {
      "id": "dependency_update_pull_request_uuid",
      "object": "dependency_update",
      "status": "published",
      "run_id": "run_uuid",
      "repository": {
        "id": "123456789",
        "full_name": "octocat/hello-world"
      },
      "title": "chore(deps): bump example from 1.0.0 to 1.0.1",
      "pull_request": {
        "number": 42,
        "url": "https://github.com/octocat/hello-world/pull/42"
      }
    }
  }
}
```

The `id` identifies the persisted dependency update pull request, not a
legacy update proposal. `run_id` is `null` when the verified pull request could
not be associated with an update run.

### Agent alert payload

Agent monitoring events use `object: "agent_alert"` and include the rule, client, severity, and alert URL:

```json
{
  "id": "evt_...",
  "type": "agent.action_blocked",
  "api_version": "2026-07-08",
  "created_at": "2026-08-04T17:40:00.000Z",
  "organization_id": "org_uuid",
  "data": {
    "object": {
      "id": "record_uuid",
      "object": "agent_alert",
      "type": "action_blocked",
      "rule": {
        "id": "exec.reverse_shell",
        "title": "Reverse shell execution",
        "severity": "high"
      },
      "client": {
        "id": "client_uuid",
        "name": "Developer workstation"
      },
      "dashboard_url": "https://superagent.sh/app/agents/alert/record_uuid"
    }
  }
}
```

The payload does not include the full normalized endpoint event stream or raw command output. Fetch the alert details in Superagent when more context is required.

## Remediation context

`finding.triage_completed` includes the context an agent needs to start remediation:

- `triage.summary` — what Superagent found during triage
- `triage.recommendation` — the recommended fix
- `triage.evidence` — structured evidence when available
- `remediation.files` — files likely involved in the fix
- `remediation.patch.diff` — a proposed unified diff when Superagent produced one
- `remediation.code_references` — relevant files, line ranges, snippets, and reasons

Patch diffs are included inline by default. If a payload exceeds the size limit, Superagent marks the patch as `truncated: true` and includes `finding_detail_url`.

Fetch `finding_detail_url` with an organization API key when your agent needs the full context:

```bash
curl https://superagent.sh/api/v1/findings/finding_uuid \
  -H "Authorization: Bearer sk_live_..."
```

Existing integrations can continue using `GET /api/findings/{finding_id}` with the `x-api-key` header. See the [REST API](https://www.superagent.sh/docs/api) for the versioned endpoint.

## Signatures

Each request includes these headers:

- `X-Superagent-Event-Id`
- `X-Superagent-Event-Type`
- `X-Superagent-Timestamp`
- `X-Superagent-Signature`

Verify the signature by computing HMAC-SHA256 over:

```text
<timestamp>.<raw-json-body>
```

using the webhook signing secret from Webhooks. The signature header format is:

```text
t=<timestamp>,v1=<hex-hmac>
```

Example verification in Node.js:

```ts
import { createHmac, timingSafeEqual } from "crypto";

function verifySuperagentWebhook(params: {
  secret: string;
  timestamp: string;
  rawBody: string;
  signature: string;
}) {
  const expectedDigest = createHmac("sha256", params.secret)
    .update(`${params.timestamp}.${params.rawBody}`)
    .digest("hex");
  const expected = `t=${params.timestamp},v1=${expectedDigest}`;

  const expectedBuffer = Buffer.from(expected);
  const actualBuffer = Buffer.from(params.signature);

  return (
    expectedBuffer.length === actualBuffer.length &&
    timingSafeEqual(expectedBuffer, actualBuffer)
  );
}
```

## Rotate or disable a target

Use the dedicated **Webhooks** page to:

- Enable or disable a target.
- Edit the target name, URL, custom request headers, event subscriptions, and sources.
- Send a test event.
- Regenerate the signing secret.
- Delete the target.

Disabling a target stops new deliveries to that URL. Regenerating the signing secret invalidates the previous secret.

## Next steps

- [Understand findings and reports](https://www.superagent.sh/docs/concepts/findings-and-reports)
- [Use Superagent MCP](https://www.superagent.sh/docs/mcp)
- [Review organization settings](https://www.superagent.sh/docs/reference/settings)

---
Source: https://www.superagent.sh/docs/webhooks
Index: https://www.superagent.sh/llms.txt
