Skip to main content
When a scan reaches a terminal status (completed or failed), Tumban issues a POST to the scan’s callback_url with a JSON body. Headers:
  • Content-Type: application/json
  • X-Tumban-Signature, X-Tumban-Signature-V2, X-Tumban-Timestamp, X-Tumban-Org-Id — when the organization has a webhook secret. See Signature verification for the full header reference and verifier snippets.

​
Body

​
scan_id
string
required
The scan id you received when submitting.
​
profile_url
string
required
The submitted profile URL.
​
status
string
required
completed or failed. See Status values for the full reference.
​
completed_at
string
required
ISO 8601 UTC timestamp.
​
recommendation
string
required
See Recommendation values. On a failed scan, Tumban defaults this to review_high so the profile lands in your queue for manual triage.
​
risk_score
integer
required
0–100. On a failed scan, defaults to 50.
​
confidence
string
required
low, medium, or high. On a failed scan, defaults to low.
​
reason_codes
string[]
required
See Reason codes. On a failed scan, this is ["SCAN_FAILED"].
​
reason_summary
string
required
Human-readable summary. On a failed scan, this contains the error message.
​
review_targets
string[]
required
URLs your reviewers should look at first. On a failed scan, this is ["manual_investigation_required"].
​
link_chain
string
required
Short label describing the path Tumban followed (e.g. Profile -> External site). Empty string on a failed scan.
​
coverage
object
required
Which analysis steps ran. See Coverage.
​
metadata
object
required
The metadata you submitted with the scan, echoed back unchanged. Always present: defaults to {} when the scan was submitted without a metadata body field.
​
evidence_index
object[]
Per-URL evidence Tumban cited in support of the decision. May be [] when Tumban reached its decision without a per-URL citation to surface. See Evidence index.
​
error
string
Present when status is failed. Brief description of what went wrong.

​
Example — completed

{
  "scan_id": "550e8400-e29b-41d4-a716-446655440000",
  "profile_url": "https://creator.example/username",
  "status": "completed",
  "completed_at": "2026-04-29T12:01:38.987654+00:00",
  "recommendation": "review_high",
  "risk_score": 85,
  "confidence": "high",
  "reason_codes": ["PROHIBITED_DOMAIN", "ADULT_KEYWORDS"],
  "reason_summary": "Direct link to a prohibited platform combined with adult keywords in bio.",
  "review_targets": ["https://prohibited-platform.example/username"],
  "link_chain": "Profile -> External site",
  "coverage": {
    "profile_scraped": true,
    "external_search_completed": true,
    "social_links_checked": 3,
    "blocked_by_login": [],
    "referrer_domains_received": 12,
    "referrer_domains_after_filter": 4,
    "referrer_matches_found": 1
  },
  "metadata": {"reviewer_id": "rv_42"},
  "evidence_index": [
    {
      "ref": "link_1",
      "url": "https://prohibited-platform.example/username",
      "type": "traversed_link",
      "domain": "prohibited-platform.example"
    }
  ]
}

​
Example — failed

{
  "scan_id": "550e8400-e29b-41d4-a716-446655440000",
  "profile_url": "https://creator.example/username",
  "status": "failed",
  "completed_at": "2026-04-29T12:01:38.987654+00:00",
  "recommendation": "review_high",
  "risk_score": 50,
  "confidence": "low",
  "reason_codes": ["SCAN_FAILED"],
  "reason_summary": "timeout_exceeded_450s",
  "review_targets": ["manual_investigation_required"],
  "link_chain": "",
  "coverage": {
    "profile_scraped": false,
    "external_search_completed": false,
    "social_links_checked": 0,
    "blocked_by_login": [],
    "referrer_domains_received": 0,
    "referrer_domains_after_filter": 0,
    "referrer_matches_found": 0
  },
  "metadata": {"reviewer_id": "rv_42"},
  "evidence_index": [],
  "error": "timeout_exceeded_450s"
}

​
Acknowledging a webhook

Tumban considers a webhook delivered when your endpoint responds with a 2xx status. Other statuses are retried — see Delivery and retries.