Skip to main content

Documentation Index

Fetch the complete documentation index at: https://octolens.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

A webhook is a destination that sends matching mentions to a URL you control. Every feed can fan out to a webhook. Point it at Zapier, an internal API, a Discord webhook, or anything else that accepts an HTTPS POST. Webhooks are available on every plan, alongside email and Slack destinations.

​
Set up a webhook

The setup flow is the same as any other destination. See Destinations for the full walkthrough. The short version:
1

Open any feed and click Set up alert

In the top-right of the feed.
2

Toggle on Webhook

Enter your Webhook URL, click Test to verify it’s reachable, and choose a Frequency: Instantly, Hourly, Daily, or Weekly.
3

Save

Click Add alert to start delivery.
Discord-compatible. Octolens webhooks work directly with Discord channel webhook URLs. Create a webhook in your Discord channel settings, copy the URL, paste it into the Webhook URL field, and mentions will post straight into the channel. No Zapier or middleware needed.
You can enable the webhook alongside Email and Slack on the same feed. All three fire off the same feed.

​
Receiving webhook requests

Octolens sends webhooks as HTTPS POST requests with a JSON body.
  • Content-Type: application/json
  • Expected response: return any 2xx status to acknowledge receipt
  • Timeout: reply promptly (under a few seconds). If your processing is slow, acknowledge first and queue the work.
Webhook signing is not currently available. For now, we recommend using a unique, unguessable endpoint URL or a secret query parameter, and validating it server-side. Do not reuse production credentials in the webhook URL.

​
Payload format

Octolens sends one mention per request. The top-level action field indicates what triggered the webhook:
  • mention_created: a new mention matched the feed

​
Example

{
  "action": "mention_created",
  "data": {
    "title": "...",
    "body": "...",
    "url": "https://...",
    "timestamp": "2024-12-04T13:55:32.000Z",
    "imageUrl": "...",
    "author": "...",
    "authorName": "...",
    "authorAvatarUrl": "...",
    "authorProfileLink": "https://...",
    "authorFollowerCount": 1234,
    "source": "reddit",
    "sourceId": "111111111",
    "relevanceScore": "high",
    "relevanceComment": "...",
    "keyword": "Octolens",
    "keywords": ["Octolens", "social listening"],
    "sentimentLabel": "Neutral",
    "tags": ["Own Brand Mention"],
    "language": "en",
    "subreddit": "r/subreddit",
    "viewId": 111,
    "viewName": "Feed name",
    "viewKeywords": ["Octolens"]
  }
}

​
Field reference

FieldTypeDescription
actionstringCurrently always mention_created.
data.titlestringPost title, if the platform has one (e.g. Reddit). Can be empty on platforms without titles.
data.bodystringThe post text.
data.urlstringCanonical URL to the post on the source platform.
data.timestampstringISO 8601 timestamp of when the post was published.
data.imageUrlstringURL of the attached image, if any.
data.authorstringThe author’s handle or username on the source platform.
data.authorNamestringThe author’s display name.
data.authorAvatarUrlstringURL to the author’s avatar image.
data.authorProfileLinkstringLink to the author’s profile.
data.authorFollowerCountnumberThe author’s follower count on the source platform, if available.
data.sourcestringThe platform the mention came from (e.g. reddit, twitter, github).
data.sourceIdstringThe platform’s native ID for the post.
data.relevanceScorestringRelevance assigned by the AI. One of high, medium, or low.
data.relevanceCommentstringOne-sentence explanation of why the mention matched.
data.keywordstringThe first (primary) keyword that matched this post. Kept for backward compatibility; new integrations should use keywords.
data.keywordsstring[]All of your keywords that matched this post. A post can match more than one.
data.sentimentLabelstringPositive, Neutral, or Negative.
data.tagsstring[]AI-assigned tags on the mention (e.g. Own Brand Mention, Buy Intent). See AI Relevance & Tags.
data.languagestringISO 639-1 language code detected for the post (e.g. en, es, de).
data.subredditstringSubreddit name. Only present for Reddit mentions.
data.viewIdnumberID of the feed that fired this webhook. (Field name kept for backward compatibility — feeds were previously called views.)
data.viewNamestringName of the feed that fired this webhook.
data.viewKeywordsstring[]The keywords configured on the feed that fired this webhook. Useful for distinguishing which feed-filter matched when one feed covers multiple keywords.
Webhook field names differ slightly from the REST API response. For example, the API returns sentiment while webhooks use sentimentLabel, and the API returns keywords as an array of objects like {id, keyword} while webhooks send keywords as an array of strings (plus keyword as a single string for backward compatibility). If you’re wiring up both, map them explicitly.

​
Use cases

Webhooks turn mentions into events in the rest of your stack. Common patterns:
  • Discord: paste a channel webhook URL straight into Octolens; mentions post into your channel
  • CRMs: create or update leads in Salesforce, HubSpot, Pipedrive, or Zoho when someone expresses buy intent
  • Task managers: open tickets in Linear, Asana, ClickUp, Monday, Trello, or Todoist from Bug Reports or User Feedback mentions
  • Chat: Microsoft Teams, or extra Slack workspaces beyond your primary connection
  • Databases: append to Notion, Airtable, or Google Sheets for custom reporting
  • Support: auto-create Intercom or Zendesk conversations from product questions
  • AI agents: trigger an agent run via MCP or your own orchestrator on every new buy-intent mention
Don’t have a direct integration? Point the webhook at Zapier, n8n, or Make and fan out from there to hundreds of other apps.

​
Customize your payload with Val Town

If you want more control than a direct webhook gives (custom message formatting, interactive buttons in Discord or Slack, per-mention routing logic, filtering before delivery) a small piece of code in the middle gets you there. Val Town is a serverless JavaScript platform built for exactly this pattern. You paste your Val Town URL into Octolens as the Webhook URL, and the val receives the payload, transforms it however you want, then forwards it on. What this unlocks:
  • Reformat the Octolens payload into a rich Discord embed or Slack Block Kit message with buttons
  • Drop fields you don’t need, or enrich the payload with data from another API before it lands
  • Edit the code in the browser and redeploy instantly. No build step, no hosting to manage
Start here:

​
Next steps

  • Destinations: the full destination setup flow (recipients, frequency, editing)
  • API Reference: pull-based alternative if you prefer polling
  • MCP Server: connect mentions to AI agents via MCP