Webhook schema reference

This page is the reference for what's in the JSON payload your webhook endpoint receives. For setup, see Webhook delivery.

Common envelope

Every webhook delivery uses the same outer shape:

{
	"notification": {
		"id": "ckq4...",
		"type": "<notification_type>",
		"organizationId": "org_abc...",
		"createdAt": "ISO-8601 string",
		"data": {
			/* type-specific — see below */
		},
		"link": "https://app.brandbanta.com/<path>"
	},
	"organization": {
		"id": "org_abc...",
		"name": "Your workspace name",
		"slug": "your-workspace-slug-abc..."
	},
	"deliveredAt": "ISO-8601 string"
}

Headers:

Header	Value
`Content-Type`	`application/json`
`User-Agent`	`BrandBanta-Webhook/1.0`
`X-BrandBanta-Signature`	HMAC-SHA256 of raw body, hex-encoded, signed with your webhook secret
`X-BrandBanta-Notification-Type`	Same as `notification.type` (for routing without parsing the body)

Always verify the signature on production endpoints. See Webhook delivery → Verifying webhook authenticity for code.

Per-type data shapes

`mention_rate_drop`

{
	"headline": "Mention rate dropped 14% this week",
	"title": "Visibility regression detected",
	"message": "Your mention rate fell from 27% to 23% across 92 scans. Drop appears on ChatGPT and Perplexity; Claude and Gemini are flat.",
	"details": {
		"previousMentionRate": 0.27,
		"currentMentionRate": 0.23,
		"deltaPp": -4,
		"deltaPercent": -0.148,
		"scopeKind": "workspace",
		"windowDays": 7,
		"platformBreakdown": {
			"openai": -0.06,
			"anthropic": 0.01,
			"googleai": 0.0,
			"perplexity": -0.07
		}
	}
}

`competitor_surge`

{
	"headline": "Competitor Bland.ai surged 18% this week",
	"title": "Competitor visibility increase",
	"message": "Bland.ai's mention rate rose from 11% to 13% across 92 scans. Surge appears on ChatGPT and Claude.",
	"details": {
		"competitorBrandId": "brand_xyz...",
		"competitorName": "Bland.ai",
		"previousMentionRate": 0.11,
		"currentMentionRate": 0.13,
		"deltaPp": 2,
		"deltaPercent": 0.182,
		"platformsCorroborated": ["openai", "anthropic"]
	}
}

`sentiment_swing`

{
	"headline": "Sentiment shifted toward negative",
	"title": "Sentiment swing detected",
	"message": "Negative sentiment share rose from 8% to 24% this week. Common themes: pricing, integration friction.",
	"details": {
		"previousSentiment": { "positive": 0.55, "neutral": 0.37, "negative": 0.08 },
		"currentSentiment": { "positive": 0.42, "neutral": 0.34, "negative": 0.24 },
		"negativeDeltaPp": 16,
		"sampleNegativeContexts": [
			"Pricing is opaque compared to alternatives",
			"Integration with HubSpot is a known pain point"
		]
	}
}

`new_competitor_detected`

{
	"headline": "New competitor 'Retell AI' detected",
	"title": "Unseen brand appearing alongside yours",
	"message": "Retell AI has been mentioned in 5 responses this week — first appearance in your tracked data.",
	"details": {
		"competitorName": "Retell AI",
		"firstSeenAt": "2026-05-19T08:32:00.000Z",
		"mentionCount": 5,
		"sampleMentionScanIds": ["scan_abc...", "scan_def..."],
		"promoteUrl": "https://app.brandbanta.com/<org-handle>/brands/discovered"
	}
}

`tier1_source_gap`

{
	"headline": "High-DR domain citing competitors but not you",
	"title": "Tier 1 source gap",
	"message": "techcrunch.com cited 3 competitors for 5 queries this week with zero mentions of your brand.",
	"details": {
		"sourceHostname": "techcrunch.com",
		"domainRatingEstimate": 91,
		"competitorsCited": ["Bland.ai", "Retell AI", "Vapi"],
		"queriesAffected": 5,
		"recommendedAction": "Pitch a guest post or PR placement targeting healthcare voice-AI angle"
	}
}

`weekly_digest`

{
	"headline": "Weekly digest — week of 2026-05-19",
	"title": "Your weekly AI visibility digest is ready",
	"message": "Mention rate held at 24%. Bland.ai surged 18%. One new competitor detected. 3 findings to act on.",
	"details": {
		"weekStart": "2026-05-19",
		"weekEnd": "2026-05-25",
		"summary": [
			"Mention rate stable at 24% across 92 scans",
			"Bland.ai surged 18% (cross-platform)",
			"New competitor 'Retell AI' first appeared mid-week"
		],
		"findingsCount": 3,
		"narrativeId": "snapshot_xyz...",
		"dashboardUrl": "https://app.brandbanta.com/<org-handle>/insights"
	}
}

`scan_completed`

{
	"headline": "Scan completed",
	"title": "Scan finished for 'voice AI for healthcare'",
	"message": "Scan against your 'voice AI for healthcare' query completed across all 4 platforms.",
	"details": {
		"scanSessionId": "scan_abc...",
		"queryId": "query_xyz...",
		"queryText": "What's the best voice AI platform for healthcare?",
		"platformResults": {
			"openai": { "mentioned": true, "sentiment": "positive" },
			"anthropic": { "mentioned": true, "sentiment": "neutral" },
			"googleai": { "mentioned": false, "sentiment": null },
			"perplexity": { "mentioned": true, "sentiment": "positive" }
		},
		"mentionedCount": 3,
		"scanUrl": "https://app.brandbanta.com/<org-handle>/scans/scan_abc..."
	}
}

Schema stability promise

Adding fields to data payloads is not a breaking change. Your endpoint must tolerate unknown keys.
Removing or renaming fields is a breaking change. We'll announce in the changelog and email all users with active webhooks 30 days before.
The envelope (notification, organization, deliveredAt) is stable.

Testing webhook payloads

The Test webhook button in Settings → Notifications → Webhook delivery sends a synthetic payload of each type so you can wire up your routing logic without waiting for real events to fire.