LLM Pulse Webhooks API

Outbound event notifications: subscribe an HTTPS URL to project events and receive HMAC-signed deliveries with no polling. Scale plan and above.

GitHub OpenAPI

Operations 4

GET /webhooks List webhook subscriptions #
POST /webhooks Create a webhook subscription #
DELETE /webhooks/{id} Delete a webhook subscription #
GET /webhooks/sample/{event_type} Sample event payloads #

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/llmpulse-ai:llmpulse-ai-webhooks-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

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. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

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

OpenAPI Specification

llmpulse-ai-webhooks-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: LLM Pulse Webhooks API
  description: 'REST API for the LLM Pulse AI visibility platform. Track brand mentions, citations, sentiment, and Share of Voice across AI-generated answers (ChatGPT, Perplexity, Gemini, Google AI Overviews, Google AI Mode, and optional add-on models). Includes the MCP (Model Context Protocol) endpoint for AI clients. MCP is available on every plan and during eligible trials via OAuth 2.1, with Bearer-token API keys also accepted for headless integrations on the Scale plan or above. Full machine-readable reference at https://llmpulse.ai/api-docs/llms-full.txt. An API key can be limited to one or several projects when it is created, and the set never changes. Such a key sees only those projects: any other project id, domain or name answers ERR_PROJECT_NOT_FOUND exactly like a project that does not exist, listings return only those projects'' rows, and operations on the whole account (creating or deleting a project, the project draft wizard) answer ERR_KEY_PROJECT_SCOPED. Operations carry vendor extensions: x-plan is the plan or entitlement the endpoint requires beyond an API key (growth, scale or reputation_access), x-write marks endpoints that need a read and write key, x-mcp-tool names the MCP tool that returns the same data, x-mcp-plan gives that tool''s plan where it differs, and x-rest-only explains an endpoint with no MCP tool. Parameters are read strictly, on REST and MCP alike: a value outside a documented enum, a boolean other than true, false, 1 or 0, an id or count that is not a plain positive number (12abc, 1.0 or 0), an id of a record the project does not have, or a from later than to answers 422 ERR_INVALID_PARAM naming the parameter, never an ignored filter. A listed value, in a query or a request body, matches in any letter case and is read in its documented spelling (granularity=Week reads as week, aggregation_type=BYPAGE as byPage, event_type=Mention.Created as mention.created). page and per_page keep their own rule: a value that is not a number reads as absent and an out-of-range one is clamped.'
  version: 1.97.0
  contact:
    name: LLM Pulse Support
    url: https://llmpulse.ai
    email: info@llmpulse.ai
  license:
    name: Proprietary
    url: https://llmpulse.ai/terms
servers:
- url: https://api.llmpulse.ai/api/v1
  description: Production API
security:
- BearerAuth: []
tags:
- name: Webhooks
  description: 'Outbound event notifications: subscribe an HTTPS URL to project events and receive HMAC-signed deliveries with no polling. Scale plan and above.'
paths:
  /webhooks:
    get:
      tags:
      - Webhooks
      summary: List webhook subscriptions
      x-llms-description: List active webhook subscriptions for the account (optional project_id filter).
      operationId: listWebhooks
      x-mcp-tool: list_webhook_subscriptions
      description: Lists active webhook subscriptions for the account, optionally filtered by project. A read-only API key receives each `target_url` masked to its scheme, host and any non-default port followed by `/…`, because the full URL can let anyone post to the receiver; a `read_write` scope key receives the full URL. Works on every plan, with an API key created on Scale too. Below Scale the subscriptions are kept but deliver nothing, and they can still be listed and deleted.
      parameters:
      - name: project_id
        in: query
        required: false
        schema:
          type: integer
        description: Optional project filter. An id that is not a plain number, or that names no project of the account, returns ERR_PROJECT_NOT_FOUND.
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
        description: Max 100
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: integer
                  per_page:
                    type: integer
                  total:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        project_id:
                          type: integer
                        event_type:
                          type: string
                          enum:
                          - mention.created
                          - competitor_mention.created
                          - citation.created
                          - prompt_execution.completed
                          - sentiment.negative_detected
                          - recommendation.completed
                          - intelligence_task.completed
                          - intelligence_task.updated
                          - geo_audit_run.completed
                          - geo_audit_alert.triggered
                          - tracking_run.completed
                        target_url:
                          type: string
                          description: The URL deliveries are sent to. A read-only API key receives only its scheme, host and any non-default port followed by `/…` (for example `https://hook.eu1.make.com/…`); a `read_write` scope key receives the full URL.
                        disabled:
                          type: boolean
                          description: True when the subscription receives no more events, including when the API key or OAuth connection that created it was revoked, or when that API key is limited to some projects and no longer covers the subscription's project. Creating it again with the same project, event and URL replaces it with a new subscription and secret.
                        failure_count:
                          type: integer
                        last_delivered_at:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        created_at:
                          type: string
                          format: date-time
                  request_id:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/PlanRequired'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Webhooks
      summary: Create a webhook subscription
      x-llms-description: Subscribe a public HTTPS URL to a project event (new brand or competitor mention, citation, execution, negative sentiment, completed recommendations report or GEO Writer task, GEO Writer edit, GEO audit run or alert, finished tracking run); deliveries are HMAC-signed. Scale plan or above.
      operationId: createWebhook
      x-mcp-tool: create_webhook_subscription
      x-plan: scale
      x-write: true
      description: 'Subscribes a public HTTPS URL to a project event. LLM Pulse POSTs a JSON envelope (`event`, `occurred_at`, `project_id`, `subscription_id`, `data`) to the URL every time the event occurs, signed via the `X-LLMPulse-Signature` header (HMAC-SHA256 of the raw body computed with the subscription secret). Failed deliveries receive up to 5 attempts in total, including the first, with backoff; subscriptions auto-disable after 20 consecutive failed deliveries. While the account is below the Scale plan its subscriptions are kept but deliver nothing: no failed delivery is counted, none is disabled, and deliveries resume once the account is back on Scale or above, without resending the events from that period. Each delivery also checks that the API key that created the subscription still covers its project: an API key limited to some projects that loses the project stops the subscription for good. Idempotent for the same project + event + URL: re-posting returns the existing subscription, unless the API key or OAuth connection that created it was revoked, or that API key no longer covers the project; then it is replaced by a new subscription with a new secret. The response carries `secret` when it creates the subscription, and on a re-post only for the API key or OAuth connection that created it: any other credential gets the subscription without `secret`. Requires a `read_write` scope API key and the Scale plan or above.'
      responses:
        '201':
          description: Created, or the existing subscription on a re-post. The signing secret is only returned by this endpoint, and on a re-post only to the credential that created the subscription.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  project_id:
                    type: integer
                  event_type:
                    type: string
                    enum:
                    - mention.created
                    - competitor_mention.created
                    - citation.created
                    - prompt_execution.completed
                    - sentiment.negative_detected
                    - recommendation.completed
                    - intelligence_task.completed
                    - intelligence_task.updated
                    - geo_audit_run.completed
                    - geo_audit_alert.triggered
                    - tracking_run.completed
                  target_url:
                    type: string
                  disabled:
                    type: boolean
                    description: True when the subscription receives no more events, including when the API key or OAuth connection that created it was revoked, or when that API key is limited to some projects and no longer covers the subscription's project. Creating it again with the same project, event and URL replaces it with a new subscription and secret.
                  failure_count:
                    type: integer
                  last_delivered_at:
                    type:
                    - string
                    - 'null'
                    format: date-time
                  created_at:
                    type: string
                    format: date-time
                  secret:
                    type: string
                    description: HMAC signing secret (whsec_...). Returned when the subscription is created, and on a re-post only to the API key or OAuth connection that created it; absent for any other credential.
                  request_id:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - project_id
              - event_type
              - target_url
              properties:
                project_id:
                  type: integer
                event_type:
                  type: string
                  enum:
                  - mention.created
                  - competitor_mention.created
                  - citation.created
                  - prompt_execution.completed
                  - sentiment.negative_detected
                  - recommendation.completed
                  - intelligence_task.completed
                  - intelligence_task.updated
                  - geo_audit_run.completed
                  - geo_audit_alert.triggered
                  - tracking_run.completed
                target_url:
                  type: string
                  description: Public HTTPS URL that will receive signed event payloads
  /webhooks/{id}:
    delete:
      tags:
      - Webhooks
      summary: Delete a webhook subscription
      x-llms-description: Delete a webhook subscription; the target URL stops receiving events immediately.
      operationId: deleteWebhook
      x-mcp-tool: delete_webhook_subscription
      x-write: true
      description: Deletes a webhook subscription; the target URL stops receiving events immediately. Requires a `read_write` scope API key. Works on every plan, with an API key created on Scale too, so a subscription paused below Scale can still be removed.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: boolean
                  id:
                    type: integer
                  request_id:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '404':
          $ref: '#/components/responses/NotFound'
  /webhooks/sample/{event_type}:
    get:
      tags:
      - Webhooks
      summary: Sample event payloads
      x-llms-description: Up to 3 example event payloads for an event type, built from recent project data (used by integration editors).
      operationId: sampleWebhookPayloads
      x-mcp-tool: get_webhook_sample
      x-plan: scale
      description: Returns up to 3 example event payloads for the event type, built from the project's most recent real data (or a static sample when the project has no data). Used by integration editors such as the Zapier sample loader. Requires the Scale plan or above.
      parameters:
      - name: event_type
        in: path
        required: true
        schema:
          type: string
          enum:
          - mention.created
          - competitor_mention.created
          - citation.created
          - prompt_execution.completed
          - sentiment.negative_detected
          - recommendation.completed
          - intelligence_task.completed
          - intelligence_task.updated
          - geo_audit_run.completed
          - geo_audit_alert.triggered
          - tracking_run.completed
      - name: project_id
        in: query
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  event_type:
                    type: string
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        event:
                          type: string
                        occurred_at:
                          type: string
                          format: date-time
                        project_id:
                          type: integer
                        subscription_id:
                          type: integer
                        data:
                          type: object
                  request_id:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/PlanRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - ERR_MISSING_AUTH
              - ERR_INVALID_API_KEY
              - ERR_REVOKED_API_KEY
              - ERR_INSUFFICIENT_SCOPE
              - ERR_INSUFFICIENT_PERMISSION
              - ERR_KEY_PROJECT_SCOPED
              - ERR_PLAN_REQUIRED
              - ERR_INTEGRATION_UNAVAILABLE
              - ERR_GENERATION_FAILED
              - ERR_ACCOUNT_INACTIVE
              - ERR_DRAFT_NOT_FOUND
              - ERR_DRAFT_STATE
              - ERR_PROJECT_NOT_FOUND
              - ERR_NOT_FOUND
              - ERR_SEARCH_CONSOLE_NOT_CONNECTED
              - ERR_SEARCH_CONSOLE_ACCESS_REVOKED
              - ERR_SEARCH_CONSOLE_UPSTREAM
              - ERR_CMS_NOT_CONNECTED
              - ERR_CMS_ACCESS_REVOKED
              - ERR_CMS_REJECTED
              - ERR_CMS_UPSTREAM
              - ERR_AI_TRAFFIC_NOT_CONNECTED
              - ERR_WEB_ANALYTICS_NOT_CONNECTED
              - ERR_WEB_ANALYTICS_INVALID_QUERY
              - ERR_WEB_ANALYTICS_ACCESS_REVOKED
              - ERR_WEB_ANALYTICS_UPSTREAM
              - ERR_AGENT_TRAFFIC_NOT_CONNECTED
              - ERR_INVALID_PARAM
              - ERR_INVALID_RANGE
              - ERR_LIMIT_REACHED
              - ERR_QUOTA_EXCEEDED
              - ERR_STALE_CONTENT
              - ERR_RATE_LIMITED
            message:
              type: string
            meta:
              type: object
              description: Extra detail for some codes. A not-connected or access-revoked error from the Search Console, AI traffic, web analytics or agent traffic endpoints carries connect_url, the in-app page where the user connects or reconnects the source. A prompt write refused because a launched pitch project's prompts are fixed carries reason pitch_prompts_frozen.
        request_id:
          type: string
  responses:
    UnprocessableEntity:
      description: Invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_INVALID_PARAM
              message: invalid metrics
            request_id: abc-123
    PlanRequired:
      description: Endpoint requires a higher plan tier
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_PLAN_REQUIRED
              message: Scale plan or above required
            request_id: abc-123
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_PROJECT_NOT_FOUND
              message: project_not_found
            request_id: abc-123
    InsufficientScope:
      description: API key lacks write permission
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_INSUFFICIENT_SCOPE
              message: insufficient_scope_write_required
            request_id: abc-123
    Unauthorized:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_MISSING_AUTH
              message: missing_authorization
            request_id: abc-123
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key authentication. Keys are managed at https://llmpulse.ai/app/api_keys (Scale plan or above). Used for the REST API and as a headless option for /mcp. A key can be limited to one or several projects when it is created; the set cannot be changed later.
    OAuth2:
      type: oauth2
      description: OAuth 2.1 with PKCE-S256 and Dynamic Client Registration. Accepted on /mcp only, available on every plan and during eligible trials. Discovery metadata at /.well-known/oauth-authorization-server.
      flows:
        authorizationCode:
          authorizationUrl: https://api.llmpulse.ai/oauth/authorize
          tokenUrl: https://api.llmpulse.ai/oauth/token
          scopes:
            mcp:read: Read data via MCP tools
            mcp:write: Create resources via MCP write tools