YouScan

YouScan Webhook API

Webhooks push new mentions to your own server in real time, so you don't have to poll the API. Every time a new mention is found and saved to a topic, YouScan sends an HTTP `POST` with the mention payload to a URL you control. ### Setup Webhooks are configured in the YouScan UI — there is **no API to create them**. Open a topic's **Settings → Integrations**, click **Add** next to *Webhook*, and enter your destination URL. Full guide: [How to use webhook integration](https://help.youscan.io/en/articles/3371690-how-to-use-webhook-integration). - Set up **per topic** — point several topics at the same URL, or add several webhooks to one topic. - Mentions are sent **automatically** via rule-based alerts, and can also be sent **manually** from the mention stream. - For a protected endpoint, put Basic Auth credentials in the URL: `https://user:password@example.com/callback`. ### Your endpoint Respond with any `2xx` status code within **4 minutes** to acknowledge receipt; any other response — or a timeout — is treated as a failed delivery. Fields with `null` values are omitted from the payload. > Mentions from Reddit, Quora and some smaller sources are not delivered. Twitter mentions > are restricted — text, URL and author details are removed.

Documentation GitHub OpenAPI

Operations 1

POST /your-webhook-endpoint Mention found #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/youscan-webhook-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: YouScan Webhook API
  version: '1.0'
  contact:
    name: YouScan Support
    url: https://youscan.io
  license:
    name: Proprietary
    url: https://youscan.io/terms-of-service
  description: 'YouScan provides a REST API to manage topics, retrieve mentions, and query statistics

    collected by the YouScan social media listening platform.'
servers:
- url: https://api.youscan.io/api/external
security:
- ApiKeyHeader: []
- ApiKeyQuery: []
tags:
- name: Webhook
  description: 'Webhooks push new mentions to your own server in real time, so you don''t have to poll the

    API.'
paths:
  /your-webhook-endpoint:
    post:
      tags:
      - Webhook
      operationId: mentionFoundWebhook
      summary: Mention found
      security: []
      servers:
      - url: https://your-app.example
        description: The HTTPS endpoint you register in the topic's Settings → Integrations.
      description: 'Sent by YouScan to the URL you configured, every time a new mention is found and

        saved to the topic. Fields with `null` values are omitted from the payload.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookMention'
            example:
              topicId: 1
              topicName: YouScan
              themeId: 1
              themeName: YouScan
              mentionId: 241032672
              url: https://youscan.io/blog/youscan-named-the-best-social-media-monitoring-software/
              published: '2021-08-09T14:13:03Z'
              addedAt: '2021-08-09T16:04:59.9506137Z'
              sourceName: youscan.io
              title: Saas Advisor Named <b>YouScan</b> a Visual Analysis Category Winner in Martech-Challenges
              text: The second year in a row, <b>YouScan</b> is named the Best Social Media Monitoring Software in the 2021 MarTech Breakthrough Awards.
              imageUrl: https://api-site.youscan.io/assets/visual-analysis.png
              author:
                name: Elena Teselko
                url: https://youscan.io/blog/youscan-named-the-best-social-media-monitoring-software/
                avatarUrl: https://assets.youscan.io/assets/main/0625ed74b3a8-512.jpeg
              sentiment: positive
              postType: post
              resourceType: blog
              spam: false
              language: eng
              country: ua
              region: Kyiv
              city: Kyiv
              tags:
              - Awards
              contentTypes:
              - text
              - image
              likes: 12
              comments: 3
              engagement: 15
              potentialReach: 100
              postId: blog-post-123
              discussionId: blog-post-123
      responses:
        '200':
          description: Return any 2xx status code to acknowledge receipt of the mention.
        4XX:
          description: 'YouScan treats any non-2xx response — or no response within 4 minutes — as a

            failed delivery.

            '
components:
  schemas:
    Sentiment:
      type: string
      enum:
      - positive
      - neutral
      - negative
      - undefined
    Reactions:
      type: object
      properties:
        total:
          type: integer
          description: Total number of reactions.
        angry:
          type:
          - integer
          - 'null'
        haha:
          type:
          - integer
          - 'null'
        love:
          type:
          - integer
          - 'null'
        sad:
          type:
          - integer
          - 'null'
        wow:
          type:
          - integer
          - 'null'
        care:
          type:
          - integer
          - 'null'
    PostType:
      type: string
      enum:
      - post
      - repost
      - extendedRepost
      - comment
    WebhookMention:
      type: object
      required:
      - topicId
      - mentionId
      - published
      - postType
      - resourceType
      properties:
        topicId:
          type: integer
          description: Topic ID.
        topicName:
          type: string
          description: Topic name.
        themeId:
          type: integer
          deprecated: true
          description: Legacy duplicate of `topicId`.
        themeName:
          type: string
          deprecated: true
          description: Legacy duplicate of `topicName`.
        mentionId:
          type: integer
          format: int64
          description: Mention identifier.
        sourceName:
          type: string
          description: Mention source (domain).
        author:
          $ref: '#/components/schemas/WebhookProfile'
          description: Author info.
        channel:
          $ref: '#/components/schemas/WebhookProfile'
          description: Publication place info.
        title:
          type: string
          description: Mention title.
        text:
          type: string
          description: Mention text.
        url:
          type: string
          description: Direct URL to the mention.
        published:
          type: string
          format: date-time
          description: Date when the mention was published (ISO 8601 format).
        addedAt:
          type: string
          format: date-time
          description: Date when the mention was saved to the topic (ISO 8601 format).
        sentiment:
          $ref: '#/components/schemas/Sentiment'
        imageUrl:
          type: string
          description: URL to the mention image.
        language:
          type: string
          description: 3-letter ISO 639 language code.
        postType:
          $ref: '#/components/schemas/PostType'
        resourceType:
          type: string
          enum:
          - social
          - blog
          - forum
          - messenger
          - news
          - reviews
          - other
          description: Source type.
        spam:
          type: boolean
          description: Whether the mention is marked as spam.
        rating:
          type: number
          description: Rating (for reviews).
        tags:
          type: array
          items:
            type: string
          description: List of tag names.
        postId:
          type: string
          description: External post ID.
        parentPostId:
          type: string
          description: External ID of the parent post.
        discussionId:
          type: string
          description: External ID of the root discussion.
        likes:
          type: integer
        reposts:
          type: integer
        comments:
          type: integer
        engagement:
          type: integer
          description: Sum of likes, reposts and comments.
        dislikes:
          type: integer
        views:
          type: integer
        impressions:
          type: integer
        reach:
          type: integer
        saves:
          type: integer
        reactions:
          $ref: '#/components/schemas/Reactions'
        contentTypes:
          type: array
          items:
            type: string
            enum:
            - text
            - link
            - image
            - video
            - poll
            - subtitles
            - sticker
        sourceFormat:
          $ref: '#/components/schemas/SourceSpecificFormat'
        country:
          type: string
          description: ISO alpha-2 country code.
        region:
          type: string
        city:
          type: string
        potentialReach:
          type: integer
          description: Potential reach.
        imageScenes:
          type: array
          items:
            type: string
          description: Scenes detected on the image. Requires the Visual Insights option.
        imageObjects:
          type: array
          items:
            type: string
          description: Objects detected on the image. Requires the Visual Insights option.
        imageColors:
          type: array
          items:
            type: string
          description: HEX color codes detected on the image. Requires the Visual Insights option.
        imageActivities:
          type: array
          items:
            type: string
          description: Activities detected on the image. Requires the Visual Insights option.
        imageBrands:
          type: array
          items:
            type: string
          description: Brands detected on the image. Requires the Visual Insights option.
    WebhookProfile:
      type: object
      properties:
        url:
          type: string
          description: Link to the profile.
        name:
          type: string
        nickname:
          type: string
        profileId:
          type: string
          description: Profile ID in the source system.
        profileType:
          type: string
          description: Profile type, specific to the source.
        avatarUrl:
          type: string
          description: Avatar image URL.
        subscribers:
          type: integer
          description: Number of subscribers (followers, friends).
        age:
          type: integer
          description: Author age. Sent only for accounts with the extended webhook feature enabled.
    SourceSpecificFormat:
      type: string
      description: Source-specific format of the post.
      enum:
      - instagramReels
      - instagramStories
      - pinterestStoryPins
      - youTubeShorts
      - facebookReels
      - facebookStories
      - tikTokPhoto
      - twitterNote
      - youTubeLive
      - facebookLive
      - twitchLive
      - twitterCommunityNote
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key authentication. The recommended way to authenticate requests.
    ApiKeyQuery:
      type: apiKey
      in: query
      name: apiKey
      description: API key as a query parameter. For testing purposes only.