Hoot Lens Webhooks API

openapi: 3.2.0
info:
  title: Hoot Lens Webhooks API
  version: v1
  summary: Read website interaction evidence and log changes.
  description: 'The Hoot Lens REST API records website interaction evidence for the sites you add and returns it as visits, recordings, heatmaps, goals, funnels and change impact. This document describes the endpoints a person or an agent uses to read that evidence and to log changes. Everything returned is observed behavior with its evidence; the API makes no claims about visitors'' emotions or intent.


    Authentication. Send `Authorization: Bearer `. The credential is either a Firebase ID token (a signed-in person, whose role on each site decides what they may do) or a personal access token (`hl_pat_...`) made in the dashboard. A personal access token carries the scopes `read`, `replay` and `annotate`, belongs to one site, expires in 30, 60 or 90 days, and can do no more than its creator''s current role allows. Operations marked `x-hootlens-sign-in-only` need a signed-in person and answer 403 to a token.


    OAuth. The hosted MCP endpoint (`/mcp`, Streamable HTTP) signs assistants in with OAuth 2.1 authorization code and PKCE (S256), with discovery at `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`. Its access tokens (`hl_oat_...`) are bound to the MCP resource and are accepted only there; sending one to any route in this document answers 401. Use a personal access token or a Firebase ID token for these routes.


    Not described here. Collector intake, public tracker configuration, billing, OAuth, sharing links, issues and feedback, invitations, members, access tokens, notifications and the audit log also exist; see docs/API.md for them.


    Site (project) IDs are public. Authorization is enforced by the API on every request. Rate limits answer 429. A caller who is not a member of a site receives 404, so a site''s existence is not revealed.'
  contact:
    name: Parallel Platforms
    url: https://hootlens.com
servers:
- url: https://hootlens-api-368877148687.us-east1.run.app
  description: Production
security:
- bearerAuth: []
tags:
- name: Webhooks
paths:
  /v1/projects/{projectId}/webhooks:
    get:
      tags:
      - Webhooks
      summary: List webhook endpoints
      description: 'The site''s webhook endpoints, newest first, with their events, whether they are enabled and how their latest deliveries went. The signing secret is never listed. `available` is false when the server cannot seal secrets, so none can be added. A site can have 5. Needs an owner or editor; personal access tokens receive 403.


        Required token scopes are listed in x-hootlens-scopes. A signed-in person needs the matching permission on the site instead (the viewer and editor roles are presets of the permissions).'
      operationId: listWebhooks
      parameters:
      - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: The endpoints.
          content:
            application/json:
              schema:
                type: object
                properties:
                  endpoints:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookEndpoint'
                  available:
                    type: boolean
                  limit:
                    type: integer
                required:
                - endpoints
                - available
                - limit
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - bearerAuth: []
      x-hootlens-scopes: []
      x-hootlens-sign-in-only: true
    post:
      tags:
      - Webhooks
      summary: Add a webhook endpoint
      description: 'Adds an https address that receives the chosen events, signed in the Standard Webhooks format. The address must be on port 443 and resolve to public addresses only (400 otherwise). The answer carries the signing secret (`whsec_...`) once; it cannot be shown again. 429 at the limit or when adding too fast, 503 when the server cannot seal secrets. Needs an owner or editor; personal access tokens receive 403.


        Required token scopes are listed in x-hootlens-scopes. A signed-in person needs the matching permission on the site instead (the viewer and editor roles are presets of the permissions).'
      operationId: createWebhook
      parameters:
      - $ref: '#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookInput'
      responses:
        '201':
          description: The endpoint and its secret.
          content:
            application/json:
              schema:
                type: object
                properties:
                  endpoint:
                    $ref: '#/components/schemas/WebhookEndpoint'
                  secret:
                    type: string
                    description: Shown once.
                required:
                - endpoint
                - secret
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - bearerAuth: []
      x-hootlens-scopes: []
      x-hootlens-sign-in-only: true
  /v1/projects/{projectId}/webhooks/{endpointId}:
    patch:
      tags:
      - Webhooks
      summary: Change a webhook endpoint
      description: 'Changes the address, name, events or whether it is enabled. Turning an endpoint back on after an automatic stop starts its failure count again. Personal access tokens receive 403.


        Required token scopes are listed in x-hootlens-scopes. A signed-in person needs the matching permission on the site instead (the viewer and editor roles are presets of the permissions).'
      operationId: updateWebhook
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/endpointId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookUpdate'
      responses:
        '200':
          description: The endpoint.
          content:
            application/json:
              schema:
                type: object
                properties:
                  endpoint:
                    $ref: '#/components/schemas/WebhookEndpoint'
                required:
                - endpoint
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - bearerAuth: []
      x-hootlens-scopes: []
      x-hootlens-sign-in-only: true
    delete:
      tags:
      - Webhooks
      summary: Delete a webhook endpoint
      description: 'Deletes the endpoint, its secret and its delivery log. Events still waiting for it are dropped. Personal access tokens receive 403.


        Required token scopes are listed in x-hootlens-scopes. A signed-in person needs the matching permission on the site instead (the viewer and editor roles are presets of the permissions).'
      operationId: deleteWebhook
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/endpointId'
      responses:
        '204':
          description: Deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - bearerAuth: []
      x-hootlens-scopes: []
      x-hootlens-sign-in-only: true
  /v1/projects/{projectId}/webhooks/{endpointId}/secret:
    post:
      tags:
      - Webhooks
      summary: Rotate a webhook secret
      description: 'Makes a new signing secret and shows it once. The old secret stops working at once. Personal access tokens receive 403.


        Required token scopes are listed in x-hootlens-scopes. A signed-in person needs the matching permission on the site instead (the viewer and editor roles are presets of the permissions).'
      operationId: rotateWebhookSecret
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/endpointId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRotate'
      responses:
        '200':
          description: The endpoint and its new secret.
          content:
            application/json:
              schema:
                type: object
                properties:
                  endpoint:
                    $ref: '#/components/schemas/WebhookEndpoint'
                  secret:
                    type: string
                    description: Shown once.
                required:
                - endpoint
                - secret
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - bearerAuth: []
      x-hootlens-scopes: []
      x-hootlens-sign-in-only: true
  /v1/projects/{projectId}/webhooks/{endpointId}/test:
    post:
      tags:
      - Webhooks
      summary: Send a test event
      description: 'Sends a `test.ping` to the endpoint now, whether or not it is enabled, with one attempt and no retries, and reports the result. A failed test never counts toward switching the endpoint off. At most 10 a minute. Personal access tokens receive 403.


        Required token scopes are listed in x-hootlens-scopes. A signed-in person needs the matching permission on the site instead (the viewer and editor roles are presets of the permissions).'
      operationId: testWebhook
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/endpointId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookTest'
      responses:
        '200':
          description: The delivery and whether it succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  delivery:
                    $ref: '#/components/schemas/WebhookDelivery'
                  ok:
                    type: boolean
                required:
                - delivery
                - ok
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - bearerAuth: []
      x-hootlens-scopes: []
      x-hootlens-sign-in-only: true
  /v1/projects/{projectId}/webhooks/{endpointId}/deliveries:
    get:
      tags:
      - Webhooks
      summary: Recent webhook deliveries
      description: 'The latest 25 deliveries to the endpoint, newest first, each with its attempts (time, HTTP status, latency, and a short snippet of a non-2xx answer). Payloads are not returned. Personal access tokens receive 403.


        Required token scopes are listed in x-hootlens-scopes. A signed-in person needs the matching permission on the site instead (the viewer and editor roles are presets of the permissions).'
      operationId: listWebhookDeliveries
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/endpointId'
      responses:
        '200':
          description: The deliveries.
          content:
            application/json:
              schema:
                type: object
                properties:
                  deliveries:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookDelivery'
                required:
                - deliveries
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - bearerAuth: []
      x-hootlens-scopes: []
      x-hootlens-sign-in-only: true
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: A short message safe to show to a person.
        code:
          type: string
          description: A stable machine-readable code, on some errors.
      required:
      - error
      additionalProperties: true
    WebhookRotate:
      type: object
      properties: {}
      additionalProperties: false
    WebhookUpdate:
      type: object
      properties:
        url:
          type: string
          minLength: 1
          maxLength: 2000
        label:
          anyOf:
          - type: string
            minLength: 1
            maxLength: 60
          - type: 'null'
        events:
          minItems: 1
          maxItems: 3
          type: array
          items:
            type: string
            enum:
            - snag.spike
            - finding.new
            - change.verdict
        enabled:
          type: boolean
    WebhookTest:
      type: object
      properties:
        event:
          type: string
          const: test.ping
      additionalProperties: false
    WebhookInput:
      type: object
      properties:
        url:
          type: string
          minLength: 1
          maxLength: 2000
        label:
          type: string
          minLength: 1
          maxLength: 60
        events:
          minItems: 1
          maxItems: 3
          type: array
          items:
            type: string
            enum:
            - snag.spike
            - finding.new
            - change.verdict
      required:
      - url
      - events
    WebhookDelivery:
      type: object
      properties:
        id:
          type: string
        eventId:
          type: string
          description: The event id, also sent as the webhook-id header.
        type:
          type: string
          enum:
          - snag.spike
          - finding.new
          - change.verdict
          - test.ping
        createdAt:
          type: integer
          description: Epoch milliseconds.
          minimum: 0
        status:
          type: string
          enum:
          - pending
          - delivered
          - failed
          - cancelled
        attemptCount:
          type: integer
        nextAttemptAt:
          type: integer
          description: While pending.
          minimum: 0
        deliveredAt:
          type: integer
          description: Epoch milliseconds.
          minimum: 0
        attempts:
          type: array
          items:
            type: object
            properties:
              at:
                type: integer
                description: Epoch milliseconds.
                minimum: 0
              status:
                type: integer
                description: The HTTP status, when the endpoint answered.
              latencyMs:
                type: integer
              error:
                type: string
                enum:
                - timeout
                - dns
                - connect
                - blocked
                - tls
                - status
                - secret
                - unavailable
              snippet:
                type: string
                description: The start of a non-2xx answer, at most 200 characters.
            required:
            - at
            - latencyMs
            additionalProperties: true
          description: The latest 10 attempts.
      required:
      - id
      - eventId
      - type
      - createdAt
      - status
      - attemptCount
      - attempts
      additionalProperties: true
    Id:
      type: string
      description: 'An identifier: 1 to 80 letters, digits, underscores or hyphens.'
      pattern: ^[a-zA-Z0-9_-]{1,80}$
    WebhookEndpoint:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        url:
          type: string
          format: uri
        label:
          type: string
        events:
          type: array
          items:
            type: string
            enum:
            - snag.spike
            - finding.new
            - change.verdict
        createdAt:
          type: integer
          description: Epoch milliseconds.
          minimum: 0
        secretRotatedAt:
          type: integer
          description: Epoch milliseconds.
          minimum: 0
        enabled:
          type: boolean
        disabledAt:
          type: integer
          description: Epoch milliseconds.
          minimum: 0
        disabledReason:
          type: string
          enum:
          - manual
          - failures
          description: 'failures: switched off after sustained failure.'
        consecutiveFailures:
          type: integer
        lastSuccessAt:
          type: integer
          description: Epoch milliseconds.
          minimum: 0
        lastFailureAt:
          type: integer
          description: Epoch milliseconds.
          minimum: 0
        lastStatus:
          type: integer
          description: The last HTTP status the endpoint answered with.
      required:
      - id
      - url
      - events
      - createdAt
      - enabled
      - consecutiveFailures
      additionalProperties: true
  responses:
    Unauthorized:
      description: The credential is missing, expired or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The site, or the record inside it, does not exist or the caller is not a member (a non-member cannot tell the two apart).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: A rate limit or a per-site limit was reached.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request fields are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The credential or the person's permissions on the site do not permit this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    endpointId:
      name: endpointId
      in: path
      required: true
      description: A webhook endpoint ID.
      schema:
        $ref: '#/components/schemas/Id'
    projectId:
      name: projectId
      in: path
      required: true
      description: The project ID. Project IDs are public identifiers, not secrets.
      schema:
        $ref: '#/components/schemas/Id'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A Firebase ID token, or a personal access token (hl_pat_...) with the scopes read, replay, annotate, configure, conversions:write. OAuth access tokens (hl_oat_...) are for the hosted MCP resource only.
externalDocs:
  description: Full API reference, including endpoints not described here
  url: https://hootlens.com/docs/API.md