{
"event": "scan.completed",
"data": {
"scan_id": "6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c",
"tier": "basic",
"status": "completed",
"company": {
"url": "https://example.nl",
"name": "Example B.V.",
"country": "NL"
},
"generated_at": "2026-07-14T10:32:11.000Z",
"llms_used": [
"openai",
"gemini",
"perplexity"
],
"prompts_count": 6,
"geo_score": 42,
"band": "emerging",
"competitors": [
{
"name": "Bol.com",
"domain": "bol.com",
"priority_score": 92,
"mentions": 18,
"prompt_consistency": 0.87,
"llm_consistency": 0.91,
"avg_rank": 1.4
}
],
"coverage": {
"providers_requested": [
"openai",
"gemini",
"perplexity"
],
"providers_reported": [
"openai",
"gemini",
"perplexity"
],
"providers_missing": []
},
"revision": 2,
"score_confidence": "high",
"meta": {
"latency_ms": 48211
}
}
}Final scan result guaranteed
Fired once per scan on completion when a callback_url was supplied — the guaranteed delivery. The payload is a full PartnerScanOutput with status “completed”; revision is 2 when a scan.preliminary fire was delivered first, otherwise 1. Deduplicate on (scan_id, revision).
Signature verification: every delivery carries an X-GetSurfaced-Signature header of the form sha256=<hex>, where <hex> is the lowercase hex HMAC-SHA256 of the EXACT raw request body bytes, keyed with your webhook signing secret (provided during partner onboarding). Compute the HMAC over the raw body BEFORE any JSON parsing/re-serialization and compare with a constant-time comparison. Both webhook events are signed with the same secret and scheme.
{
"event": "scan.completed",
"data": {
"scan_id": "6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c",
"tier": "basic",
"status": "completed",
"company": {
"url": "https://example.nl",
"name": "Example B.V.",
"country": "NL"
},
"generated_at": "2026-07-14T10:32:11.000Z",
"llms_used": [
"openai",
"gemini",
"perplexity"
],
"prompts_count": 6,
"geo_score": 42,
"band": "emerging",
"competitors": [
{
"name": "Bol.com",
"domain": "bol.com",
"priority_score": 92,
"mentions": 18,
"prompt_consistency": 0.87,
"llm_consistency": 0.91,
"avg_rank": 1.4
}
],
"coverage": {
"providers_requested": [
"openai",
"gemini",
"perplexity"
],
"providers_reported": [
"openai",
"gemini",
"perplexity"
],
"providers_missing": []
},
"revision": 2,
"score_confidence": "high",
"meta": {
"latency_ms": 48211
}
}
}Authorizations
Partner API key as a Bearer token: Authorization: Bearer gsk_live_.... Live keys (gsk_live_) run real scans; test keys (gsk_test_) run request validation then return deterministic sandbox mocks (sandbox: true, nothing persisted, no rate-limit consumption). Keys are issued per partner and are revokable.
Body
Envelope for every webhook event. The signed bytes are exactly this JSON document as transmitted.
data is discriminated by event: scan.preliminary and scan.completed carry a PartnerScanOutput, scan.failed carries a PartnerScanFailedOutput (score fields absent, error present). Switch on event before reading data.
The single scan result contract. Returned by POST (sync completion), GET status polls, and inside both webhook events — partners always see this one shape regardless of entry point. Sandbox (test-key) responses add a top-level sandbox: true extension field.
- Option 1
- Option 2
Show child attributes
Show child attributes
Response
Return any 2xx to acknowledge receipt. Non-2xx responses are retried (durable delivery via queue).