Scanner results API

Before posting scanner results

Use this page when the scanner runtime has finished an authorized scan attempt and must post the result back into WebRiskOps. The endpoint accepts either a completed scan payload with pages, artifacts and issues, or a failed scan payload with an error summary.

• Use placeholder values only; never paste real API keys, webhook secrets, tokens or customer data into documentation examples.
• Send results only for a known scan run ID that WebRiskOps created for the current project.
• Keep raw screenshots and HTML artifacts in artifact storage, not inline API examples.

Post a scanner result

Follow the path `Authentication and headers → Scanner runtime → POST /api/scanner/results → Scan run update → Report workflow`.

1. Open Authentication and headers and confirm `X-Scanner-Secret` plus `Idempotency-Key` rules for scanner postbacks. Result: auth and retry expectations are clear before the scanner sends data.
2. Start from the scanner runtime for an existing `scanRunId`. Result: unknown, missing or non-integer scanRunId values return validation errors instead of creating unrelated scan records.
3. Send `POST /api/scanner/results` with `Content-Type: application/json` and `X-Scanner-Secret: ${WRO_SCANNER_SHARED_SECRET}`. Result: route name `scanner.results.store` accepts only the configured scanner shared secret.
4. For completed scans, set `status` to `completed` and include `page.url`, `page.normalizedUrl`, `page.statusCode`, `page.pageType` and `page.responseHeaders`. Result: the scan page stores the tested URL, normalized URL, HTTP status, page type and response headers.
5. Include `artifacts.screenshotPath` and optional `artifacts.htmlSnapshotPath`. Result: screenshots and HTML snapshots stay in artifact storage instead of being embedded in the JSON request.
6. Include `issues` with category, type, severity, title, description, fingerprint, confidence, evidence and optional screenshotPath. Result: findings are persisted with stable fingerprints and sensitive evidence text is sanitized before storage.
7. For multi-page results, send `pages[]` entries with their own page, artifacts and issues, and include optional counters such as `counters.pagesScanned`, `issuesCount`, `highCount`, `mediumCount`, `lowCount` and `riskScore`. Result: dashboard counters use scanner totals when present or derive them from the payload.
8. For failed scans, set `status` to `failed` and include `error.code` and `error.message` with optional error URL or timeoutMs. Result: the scan run is marked failed, reserved scan credit is restored, temporary artifacts are cleaned and failure automation runs.
9. Reuse the same `Idempotency-Key` only for the same scanner attempt retry. Result: terminal scan runs ignore duplicate completed postbacks instead of creating extra scan pages or issues.
10. Continue to scan detail, report workflow or Errors, idempotency, retries and rate limits after the response. Result: `202 Accepted`, `401 Unauthorized` and `422 Validation failed` each point to a concrete next action.

Configure completed scan payload

Completed scan payloads should be deterministic and evidence-safe.

• `scanRunId` must be a strict integer of at least 1 and must exist in `scan_runs.id`.
• `status` must be `completed` or `failed`.
• Single-page payloads use top-level `page`, `artifacts` and `issues`; multi-page payloads use `pages[]`.
• `page.responseHeaders` must be an object whose values are strings.
• `page.consoleErrorsCount` and `page.networkErrorsCount` are optional non-negative integers.
• `issues.*.fingerprint`, `issues.*.category`, `issues.*.severity`, `issues.*.confidence`, `issues.*.businessImpact`, `issues.*.suggestedRemediation` and `issues.*.reproductionSteps` should describe the finding without secrets or raw private artifacts.
• `error.code`, `error.message`, optional `error.url` and optional `error.timeoutMs` are required only for failed scans.

Ready scanner result states

Continue only when the postback can update the intended scan run.

• Auth ready means `X-Scanner-Secret` matches the configured scanner shared secret.
• Scan run ready means `scanRunId` exists and belongs to the scan attempt that produced the payload.
• Completed payload ready means status is completed and page, artifacts and issues are present.
• Failed payload ready means status is failed and error.code plus error.message explain the failure.
• Artifact reference ready means screenshotPath and htmlSnapshotPath point to storage paths, not inline screenshots or HTML.
• Retry ready means `Idempotency-Key` represents the same scanner attempt if the postback is retried.

Blocked scanner result states

Blocked scanner postbacks should explain exactly what to fix.

• `UNAUTHORIZED` means `X-Scanner-Secret` is missing, invalid or the scanner shared secret is not configured.
• `VALIDATION_FAILED` means required payload fields are missing, malformed or use an unsupported enum value.
• `SCAN_RUN_NOT_FOUND` means scanRunId does not reference a known scan run.
• Missing page.responseHeaders or artifacts.screenshotPath blocks completed scan ingestion.
• Invalid page status codes, non-string response headers, unknown page types or issue confidence outside 0-100 return field-specific validation errors.
• Secret values inside evidence, failure messages or reproduction steps are redacted before storage; rotate any exposed scanner or customer secret before retrying.

Continue after scanner postback

After a successful postback, continue to the scan detail and report workflow so the customer can review persisted pages, artifacts, issues, counters and report status. Use Request and response examples for copyable placeholder payloads, Authentication and headers for auth failures, and Errors, idempotency, retries and rate limits when a scanner retry or validation failure needs interpretation.