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
}eventType
The type of event that triggered this notification (e.g., session.completed)
timestamp
ISO 8601 formatted timestamp of when the event occurred
metadata
Optional 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_read
reading
finished
abandoned
Session Status
active
paused
completed