Scan-result callback

This page is auto-generated from src/events/callback.ts. Do not edit by hand — see docs/dev/docs-auto-sync.md.

Inbound callback from customer-side (BYOS) scanners reporting verdicts back to Upwarden.

Route

Method	Path
POST	/api/v1/callbacks/scan-result

Signature verification

Mechanism: Bearer JWT (RS256, per-tenant JWKS)

Transport: Authorization: Bearer <jwt> header

Bearer JWT signed with the tenant’s RS256 key. The tenant is selected via the iss claim, and the public key is loaded from either tenant.jwksUrl (remote JWKS fetched with SSRF-safe URL validation) or tenant.jwksPublicKey (static SPKI). aud is pinned to vanguard, algorithms is locked to RS256, and exp is in requiredClaims so unbounded tokens are rejected.

Idempotency

INSERT ... ON CONFLICT DO NOTHING on the deliveries table, keyed on the signed event id. The loser of a concurrent race reads back the winner’s row and returns the same response — no double-action.

Retry posture

Retry posture is governed by the upstream’s webhook delivery contract. Upwarden responds 2xx on accepted deliveries (including known-no-op events) so the upstream stops retrying; transient failures return 5xx so the upstream re-delivers within its retry budget.

Request body

ScanResultPayload

Field	Type	Optional
event_id	string	yes
package	string	yes
version	string	yes
ecosystem	string	yes
verdict	"SAFE" | "BLOCKED"	yes
scanner_id	string	yes
evidence_url	string	yes

ScanResultBody

Field	Type	Optional
event_id	string	no
verdict	"SAFE" | "BLOCKED"	no
scanner_id	string	no
evidence_url	string	yes
ecosystem	string	yes

Dispatch tables

No dispatch tables found in source.

Architecture preamble

The leading doc-comment block from the source file, reproduced verbatim. This is the canonical narrative explanation of the receiver — the auto-generated sections above are derived from it.

No leading doc-comment block found in source.