Payload format

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

string

required

The scan id you received when submitting.

string

required

The submitted profile URL.

string

required

completed or failed. See Status values for the full reference.

string

required

ISO 8601 UTC timestamp.

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.

integer

required

0–100. On a failed scan, defaults to 50.

string

required

low, medium, or high. On a failed scan, defaults to low.

string[]

required

See Reason codes. On a failed scan, this is ["SCAN_FAILED"].

string

required

Human-readable summary. On a failed scan, this contains the error message.

string[]

required

URLs your reviewers should look at first. On a failed scan, this is ["manual_investigation_required"].

string

required

Short label describing the path Tumban followed (e.g. Profile -> External site). Empty string on a failed scan.

object

required

Which analysis steps ran. See Coverage.

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.

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.

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.

Get started

Core concepts

API reference

Webhooks

Reference

Payload format

Body

Example — completed

Example — failed

Acknowledging a webhook

​Body

​Example — completed

​Example — failed

​Acknowledging a webhook

Body

Example — completed

Example — failed

Acknowledging a webhook