{
"event": "scan.preliminary",
"data": {
"scan_id": "6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c",
"tier": "basic",
"status": "preliminary",
"company": {
"url": "https://example.nl",
"name": "Example B.V.",
"country": "NL"
},
"generated_at": null,
"llms_used": [
"openai",
"gemini",
"perplexity"
],
"prompts_count": 6,
"geo_score": 38,
"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",
"perplexity"
],
"providers_missing": [
"gemini"
]
},
"revision": 1,
"score_confidence": "reduced",
"meta": {
"latency_ms": null
}
}
}Preliminary scan snapshot best effort revision 1
Fired at most once per scan, only when a callback_url was supplied AND the scan outlived the create endpoint’s sync-wait window with at least one provider reported. Best-effort: there is deliberately no retry backstop — a scan may skip straight to scan.completed. The payload is a full PartnerScanOutput with status “preliminary” and revision 1. Verify the signature before trusting the payload (see the signature note on scan.completed — both events use the identical scheme). Deduplicate on (scan_id, revision).
{
"event": "scan.preliminary",
"data": {
"scan_id": "6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c",
"tier": "basic",
"status": "preliminary",
"company": {
"url": "https://example.nl",
"name": "Example B.V.",
"country": "NL"
},
"generated_at": null,
"llms_used": [
"openai",
"gemini",
"perplexity"
],
"prompts_count": 6,
"geo_score": 38,
"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",
"perplexity"
],
"providers_missing": [
"gemini"
]
},
"revision": 1,
"score_confidence": "reduced",
"meta": {
"latency_ms": null
}
}
}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).