Webhooks push real-time notifications to your server whenever something happens in MentionFox -- a scan completes, a new mention is found, a contact gets enriched, and more. No polling required.
| Event | Trigger | Payload Includes |
|---|---|---|
scan.completed | A scan run finishes | Scan ID, client ID, platforms scanned, mention count |
mention.new | New mention discovered | Mention ID, platform, URL, title, sentiment |
mention.sentiment_change | Sentiment re-scored | Mention ID, old sentiment, new sentiment |
contact.enriched | Person enrichment completes | Contact ID, enrichment type (light/deep), fields updated |
contact.created | New contact added | Contact ID, name, source |
dossier.ready | Deep dossier generation finishes | Contact ID, dossier summary |
dealflow.stage_change | Lead moves pipeline stages | Lead ID, old stage, new stage |
report.generated | Client report is ready | Report ID, client ID, download URL |
credits.low | Credits fall below 10% | Credits remaining, allowance |
All webhook payloads are JSON and follow a consistent structure:
{
"event": "mention.new",
"timestamp": "2026-04-05T14:22:00Z",
"data": {
"id": "mention_xyz789",
"client_id": "75db6a1c-...",
"platform": "twitter",
"title": "Great experience with @YourBrand",
"url": "https://twitter.com/user/status/...",
"sentiment": "positive"
}
}If you set a signing secret, MentionFox includes an X-MentionFox-Signature header with each request. Verify it to ensure the payload was sent by MentionFox and not tampered with.
// Node.js example
const crypto = require('crypto');
function verifyWebhook(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}If your endpoint returns a non-2xx status code or times out (10-second limit), MentionFox retries with exponential backoff:
After 5 failed attempts, the event is marked as failed. You can view and manually retry failed deliveries in Settings > Integrations > Webhooks > Delivery Log.