Change feed

The change feed, GET /v1/changes, lists your tenant's events oldest first. Poll it with a cursor you store, and you read every event exactly in order, without exposing a public endpoint.

It carries the same events as webhooks, in the same shape and with the same ids. Test events never appear in it.

Webhooks or the change feedCopy Anchor Link

You can use both: an event's id is the same in each, so deduplicate on it.

Read the feedCopy Anchor Link

curl "https://api.workwae.com/v1/changes?limit=100" \
  -H "Authorization: Bearer $WORKWAE_API_KEY"

{
  "items": [
    {
      "id": "1001",
      "type": "message.created",
      "accountId": "6f1c2a4e-8b3d-4e5f-9a7b-1c2d3e4f5a6b",
      "createdAt": "2026-05-04T09:30:00.000Z",
      "data": { "message": { "id": "c4e6a8b0-…" }, "mailboxes": [] }
    }
  ],
  "nextCursor": "MTAwMQ"
}

Cursors and empty pagesCopy Anchor Link

• nextCursor is never null: the feed has no end. Always store it and pass it back as cursor.
• An empty page means you are caught up. Keep the same cursor and poll again later.
• With types set, nextCursor may move past events that did not match, so the next request does not rescan them.
• A cursor Workwae did not produce answers with reason invalid_cursor.

RetentionCopy Anchor Link

Events are kept for the tenant's eventRetentionDays setting, 7 to 30 days. The feed starts at the oldest event still retained.

Account-limited API keysCopy Anchor Link

An API key limited to some accounts reads only those accounts' events. Tenant-level events (accountId null) are left out.

Polling loopCopy Anchor Link

Save the cursor after handling each page, so a restart resumes where it stopped. Wait before polling again when a page is empty.

import { setTimeout as sleep } from "node:timers/promises";

let cursor = await loadCursor(); // undefined the first time

for (;;) {
  const page = await workwae.changes.list({ cursor, limit: 100 });
  for (const event of page.items) {
    await handle(event); // { id, type, accountId, data, createdAt }
  }
  cursor = page.nextCursor;
  await saveCursor(cursor);
  if (page.items.length === 0) await sleep(5_000);
}

The SDK's changes helper iterates events until the feed is caught up and exposes the position to save:

import { changes } from "@workwae/sdk";

const feed = changes(workwae.changes.list, { cursor: await loadCursor() });
for await (const event of feed) await handle(event);
await saveCursor(feed.cursor);

See the changes reference for the full operation.