Webhooks

Webhooks send new mentions to your app as JSON. Add your webhook URL in Settings > API key & webhook.

When webhooks are sent

sociallisteningapi sends an HTTP POST request after a scheduled monitoring run finds new mentions with a relevance score of 2 or higher.

Delivery is not instant. Monitoring times vary by platform.
Each request contains new mentions from one platform.
A request may contain more than one mention in the mentions array.
No request is sent when a monitoring run has no matching new mentions.

When you add a keyword, sociallisteningapi immediately backfills and saves the mentions it finds. Backfilled mentions do not trigger webhooks. Webhooks begin with new mentions found during later scheduled monitoring runs.

Your endpoint should return a 2xx response within 15 seconds. Failed requests are not retried.

Request

Method: POST
Content-Type: application/json
Authentication: None

The same payload format is used for every platform. Fields that do not apply to a platform are sent as null.

JSON example

{
  "type": "mentions.scraped",
  "organizationId": "org_123",
  "platform": "REDDIT",
  "mentionCount": 1,
  "sentAt": "2026-07-18T01:30:00.000Z",
  "mentions": [
    {
      "id": 2001,
      "keywordId": 4001,
      "keywordValue": "sociallisteningapi",
      "projectId": 3001,
      "platform": "REDDIT",
      "platformPostId": "1e4example",
      "permalink": "https://www.reddit.com/r/saas/comments/1e4example/",
      "subreddit": "saas",
      "authorHandle": "example_user",
      "text": "Has anyone tried sociallisteningapi for social monitoring?",
      "sourceCreatedAt": "2026-07-18T01:21:42.000Z",
      "createdAt": "2026-07-18T01:29:51.000Z",
      "commentStatus": 0,
      "relevance": 4
    }
  ]
}

Payload fields

Field	Type	Description
`type`	string	Event name. Currently `mentions.scraped`.
`organizationId`	string	Your sociallisteningapi organization ID.
`platform`	string	Platform checked during this monitoring run.
`mentionCount`	integer	Number of items in the `mentions` array.
`sentAt`	string	Time the webhook was sent, in ISO 8601 format.
`mentions`	array	New mentions found during the monitoring run.

Mention fields

Field	Type	Description
`id`	integer or null	sociallisteningapi mention ID.
`keywordId`	integer or null	ID of the keyword that matched.
`keywordValue`	string or null	Keyword that matched the mention.
`projectId`	integer or null	Project linked to the keyword.
`platform`	string or null	Source platform: `REDDIT`, `X`, `LINKEDIN`, `HN`, `YOUTUBE`, `BLUESKY`, `TIKTOK`, `MEDIUM`, or `GITHUB`.
`platformPostId`	string or null	ID assigned by the source platform.
`permalink`	string or null	Link to the original post or comment.
`subreddit`	string or null	Subreddit name for Reddit mentions. `null` for other platforms.
`authorHandle`	string or null	Author username or handle, when available.
`text`	string	Text captured from the source.
`sourceCreatedAt`	string or null	Time the source post was published, in ISO 8601 format.
`createdAt`	string or null	Time sociallisteningapi saved the mention, in ISO 8601 format.
`commentStatus`	integer	Review status: `0` pending, `1` accepted, or `-1` declined.
`relevance`	integer or null	sociallisteningapi relevance score.

Written by MelSocial media and customer support at sociallisteningapi