ListRecentEventsResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/huddlekit/json-schema/huddlekit-list-recent-events-response-schema.json",
  "title": "ListRecentEventsResponse",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/huddlekit-events-api-openapi.yml#/components/schemas/ListRecentEventsResponse",
  "type": "object",
  "required": [
    "events",
    "sample"
  ],
  "properties": {
    "events": {
      "type": "array",
      "description": "Sample payloads built from the newest comments, newest first.",
      "items": {
        "$ref": "#/$defs/WebhookPayload"
      }
    },
    "sample": {
      "type": "boolean",
      "const": true,
      "description": "Always true: these are samples, not replayed deliveries."
    }
  },
  "$defs": {
    "Change": {
      "type": "object",
      "description": "Before and after values of a changed field.",
      "required": [
        "old",
        "new"
      ],
      "properties": {
        "old": {
          "description": "Previous value. Always null for text edits (the pre-edit text is never sent) and for screenshots."
        },
        "new": {
          "description": "New value."
        }
      }
    },
    "DocumentPage": {
      "type": "object",
      "title": "Document page",
      "description": "Location of a document comment.",
      "additionalProperties": false,
      "required": [
        "page_number"
      ],
      "properties": {
        "page_number": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Page number (1-based)."
        },
        "video_timestamp": {
          "type": "number",
          "description": "Position in seconds. Present only for comments on a video."
        }
      }
    },
    "EventType": {
      "type": "string",
      "enum": [
        "comment.created",
        "comment.status_changed",
        "comment.text_changed",
        "comment.screenshot_ready"
      ],
      "description": "`comment.created`: a comment was added. `comment.status_changed`: its status changed. `comment.text_changed`: its text was edited. `comment.screenshot_ready`: its screenshot finished capturing (website and webapp comments only). The **Send test event** button in the Huddlekit app also sends `ping`, with a made-up comment and no `source` or `permalink`; answer it with any 2xx and don't treat it as a real event."
    },
    "Surface": {
      "type": "string",
      "enum": [
        "website",
        "webapp",
        "document"
      ],
      "description": "What a comment is attached to. `website`: a website project (the parent is a project). `webapp`: a web app that runs the Huddlekit SDK widget (the parent is a web app). `document`: an uploaded PDF, image or video (the parent is a document)."
    },
    "WebappPage": {
      "type": "object",
      "title": "Web app page",
      "description": "Location of a web app comment.",
      "additionalProperties": false,
      "required": [
        "url",
        "path",
        "title"
      ],
      "properties": {
        "url": {
          "type": [
            "string",
            "null"
          ],
          "description": "Full URL of the page."
        },
        "path": {
          "type": [
            "string",
            "null"
          ],
          "description": "Page path."
        },
        "title": {
          "type": [
            "string",
            "null"
          ],
          "description": "Page title."
        }
      }
    },
    "WebhookAuthor": {
      "type": "object",
      "description": "Who wrote the comment.",
      "required": [
        "name",
        "kind"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Display name, or `Someone` when the name is unknown. Comments created through this API show as `API`."
        },
        "kind": {
          "type": "string",
          "enum": [
            "user",
            "guest"
          ],
          "description": "`user` for a Huddlekit member, `guest` for anyone else."
        }
      }
    },
    "WebhookComment": {
      "type": "object",
      "description": "The comment as it is when the event is sent.",
      "required": [
        "id",
        "number",
        "title",
        "text",
        "status",
        "page",
        "permalink",
        "screenshot",
        "browser_info",
        "author",
        "created_at"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Comment id."
        },
        "number": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Sequential number of the comment within its parent."
        },
        "title": {
          "type": "string",
          "description": "One-line title made from the text: its first line, shortened to about 80 characters, ending in … when anything was cut."
        },
        "text": {
          "type": "string",
          "description": "Full comment text."
        },
        "status": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "open",
            "in-review",
            "in-progress",
            "resolved",
            null
          ],
          "description": "Workflow status: `open`, `in-review`, `in-progress` or `resolved`."
        },
        "page": {
          "description": "Where the comment is. Shape depends on `surface`.",
          "oneOf": [
            {
              "$ref": "#/$defs/WebsitePage"
            },
            {
              "$ref": "#/$defs/WebappPage"
            },
            {
              "$ref": "#/$defs/DocumentPage"
            }
          ]
        },
        "permalink": {
          "type": "string",
          "format": "uri",
          "description": "Link back to the comment. For website and document comments it opens the comment in Huddlekit; for web app comments it opens your page with the Huddlekit widget."
        },
        "screenshot": {
          "type": [
            "string",
            "null"
          ],
          "description": "Screenshot of the page, or null. Always null for documents."
        },
        "browser_info": {
          "description": "Browser and device details recorded with the comment (JSON), or null. Always null for documents."
        },
        "author": {
          "description": "Who wrote the comment, or null when unknown.",
          "oneOf": [
            {
              "$ref": "#/$defs/WebhookAuthor"
            },
            {
              "type": "null"
            }
          ]
        },
        "created_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When the comment was created."
        }
      }
    },
    "WebhookPayload": {
      "type": "object",
      "description": "Body of every webhook delivery, and of each item returned by `GET /events/recent`.",
      "required": [
        "event",
        "event_id",
        "occurred_at",
        "workspace_id",
        "surface",
        "parent_id",
        "source",
        "comment",
        "changed"
      ],
      "properties": {
        "event": {
          "$ref": "#/$defs/EventType"
        },
        "event_id": {
          "type": "string",
          "description": "Unique event id; the same on every retry, so use it to de-duplicate. Samples from `GET /events/recent` use `sample:<comment id>`."
        },
        "occurred_at": {
          "type": "string",
          "format": "date-time",
          "description": "When the change happened."
        },
        "workspace_id": {
          "type": "string",
          "format": "uuid",
          "description": "Workspace the comment belongs to."
        },
        "surface": {
          "$ref": "#/$defs/Surface"
        },
        "parent_id": {
          "type": "string",
          "description": "Id of the project, web app or document the comment is on."
        },
        "source": {
          "type": [
            "string",
            "null"
          ],
          "description": "Who made the change: `app` (a change made in Huddlekit, or synced back from Slack, Linear, ClickUp or Notion), `mcp` (an AI agent via Huddlekit's MCP server) or `connector:<api_key_id>` (a call to this API with that key). Null only on events from before 2026-09-06."
        },
        "comment": {
          "description": "The comment. Typed as nullable, but events whose comment no longer exists are not sent.",
          "oneOf": [
            {
              "$ref": "#/$defs/WebhookComment"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed": {
          "type": [
            "object",
            "null"
          ],
          "description": "What changed, keyed by field: `status` for comment.status_changed, `text` for comment.text_changed (with `old` always null), `screenshot` for comment.screenshot_ready (with `old` null). Null for comment.created.",
          "additionalProperties": {
            "$ref": "#/$defs/Change"
          }
        }
      }
    },
    "WebsitePage": {
      "type": "object",
      "title": "Website page",
      "description": "Location of a website comment.",
      "additionalProperties": false,
      "required": [
        "path"
      ],
      "properties": {
        "path": {
          "type": [
            "string",
            "null"
          ],
          "description": "Page path, relative to the project's URL."
        }
      }
    }
  }
}