// interfaces
Webhooks
Send red-team report, finding, dependency and image validation, contributor trust, and agent monitoring events to your own systems.
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.
Create a webhook target
- Open Webhooks in the sidebar.
- Select Add webhook.
- Enter a target name, for example
Remediation agent. - Enter a valid HTTPS URL.
- Optionally add request headers, for example
Authorizationfor an authenticated receiver such as a Cursor automation webhook. Header values are encrypted at rest. - Choose the events this target should receive.
- In the grouped Sources dropdown, select one or more entire groups or specific repositories, applications, agents, and images.
- 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 to start and poll scans.
Delivery
Superagent sends webhook requests as POST requests with a JSON body.
Your endpoint should:
- Return any
2xxresponse 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.
{
"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.
Report payload
Report events use object: "report" and a type of repository, web_app,
or agent:
{
"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:
{
"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:
{
"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:
{
"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 triagetriage.recommendation— the recommended fixtriage.evidence— structured evidence when availableremediation.files— files likely involved in the fixremediation.patch.diff— a proposed unified diff when Superagent produced oneremediation.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:
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 for the versioned endpoint.
Signatures
Each request includes these headers:
X-Superagent-Event-IdX-Superagent-Event-TypeX-Superagent-TimestampX-Superagent-Signature
Verify the signature by computing HMAC-SHA256 over:
<timestamp>.<raw-json-body>using the webhook signing secret from Webhooks. The signature header format is:
t=<timestamp>,v1=<hex-hmac>Example verification in Node.js:
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.