Payload Structure

Understand the JSON payload structure sent to webhooks and integrations.

Base Payload

Every webhook payload includes these base fields. The book, session, and shelf objects are included depending on the event type.

{
  "eventType": "session.completed",
  "timestamp": "2024-12-04T10:30:00Z",
  "book": { ... },
  "session": { ... },
  "shelf": null,
  "metadata": null
}

eventTypeThe type of event that triggered this notification (e.g., session.completed)

timestampISO 8601 formatted timestamp of when the event occurred

metadataOptional additional data (currently null, reserved for future use)

Book Object

Included in book-related events and session events. Contains details about the book.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "The Great Gatsby",
  "authors": ["F. Scott Fitzgerald"],
  "pages": 180,
  "currentPage": 180,
  "status": "finished",
  "isbn": "9780743273565",
  "progressPercentage": 100
}

Field	Type	Description
`id`	string	Unique identifier for the book (UUID)
`title`	string	The title of the book
`authors`	string[]	Array of author names
`pages`	number	Total number of pages in the book
`currentPage`	number	Current reading position (page number)
`status`	string	Reading status (to_read, reading, finished, abandoned)
`isbn`	string?	ISBN number if available (optional)
`progressPercentage`	number	Reading progress as a percentage (0-100)

Session Object

Included in session events. Contains details about the reading session.

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "startedAt": "2024-12-04T10:05:00Z",
  "endedAt": "2024-12-04T10:30:00Z",
  "status": "completed",
  "durationMinutes": 25,
  "pagesRead": 42
}

Field	Type	Description
`id`	string	Unique identifier for the session (UUID)
`startedAt`	string	ISO 8601 timestamp when the session started
`endedAt`	string?	ISO 8601 timestamp when the session ended (null if active)
`status`	string	Session status (active, paused, completed)
`durationMinutes`	number	Duration of the session in minutes
`pagesRead`	number	Number of pages read during this session

Shelf Object

Included in shelf-related events. Contains details about the shelf.

{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "name": "Favorites",
  "icon": "star.fill",
  "bookCount": 12
}

Field	Type	Description
`id`	string	Unique identifier for the shelf (UUID)
`name`	string	Name of the shelf
`icon`	string?	SF Symbol name for the shelf icon (optional)
`bookCount`	number	Number of books on this shelf

Status Values

Book Status

to_readreadingfinishedabandoned

Session Status

activepausedcompleted

Back to Webhooks