Skip to content
Shortcut: /, ⌘K or Ctrl+K

Event history

List event metadata and retrieve available exact webhook payload bytes for an team or project.

View as Markdown

The Platform API records a bounded history of team and project events. Use it to inspect what happened before checking the related webhook deliveries. History, webhooks, event streams, polymorfa listen, and the MCP event tools contain only the event types documented in the webhook reference, plus test events you create.

Team events include customer lifecycle and campaign lifecycle activity:

HTTP
GET /platform/events
GET /platform/events/{eventId}

Project events cover activity owned by one project:

HTTP
GET /platform/projects/{projectId}/events
GET /platform/projects/{projectId}/events/{eventId}

All four routes require events:read. Project credentials can access only the project routes for their bound project. Team credentials use the team routes directly and can select a project through the project route prefix.

List events#

List routes return newest events first. Filter by exact event type, since, or exclusive until. A page contains at most 100 items and includes an opaque nextCursor when more items remain.

cURL
curl "https://api.polymorfa.com/platform/projects/$PROJECT_ID/events?type=message.received&limit=100" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
TypeScript
for await (const event of await project.events.list({ type: "message.received", limit: 100 })) {
  console.log(event.id, event.type, event.createdAt, event.payloadAvailability);
}

TypeScript:

A project client sees its project. A team client sees team events and every project's events. The loop fetches the next pages for you; see Read every page in the SDK.

Do not modify or decode a cursor. A cursor is bound to its owner and filters. Send it with limit only; changing the filters returns invalid_cursor.

To follow new events in ingestion order, pass afterOffset=0. The response includes page.highWatermark, the last committed stream position. Use that value as afterOffset on the next request to wait for new events. If a response has page.hasMore=true, use page.nextOffset first and continue until the page is exhausted. This mode accepts type and limit; it cannot be combined with cursor, since, or until. An event delivered after a reconnect appears after its stream position even if its createdAt is older than earlier events. Offsets are decimal strings; keep them as strings.

cURL
curl "https://api.polymorfa.com/platform/projects/$PROJECT_ID/events?afterOffset=$OFFSET&limit=100" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
TypeScript
import { setTimeout as wait } from "node:timers/promises";

// Baseline: start after everything stored so far.
let offset = (await project.events.listIndexed({ afterOffset: "0", limit: 1 })).page.highWatermark ?? "0";
const stop = new AbortController(); // Call stop.abort() to stop following.

while (!stop.signal.aborted) {
  const result = await project.events.listIndexed({ afterOffset: offset, limit: 100 });
  for (const event of result.items) console.log(event.id, event.type);

  // Keep the saved offset when a page names no later position.
  const next = result.page.hasMore ? result.page.nextOffset : result.page.highWatermark;
  const advanced = next != null && BigInt(next) > BigInt(offset);
  if (advanced) offset = next;
  // Caught up means no more events yet. Wait before asking again; never spin.
  if (!result.page.hasMore || !advanced) await wait(5_000, undefined, { signal: stop.signal }).catch(() => {});
}

TypeScript:

listIndexed returns events in ingestion order. Start from a baseline, then poll from the saved offset. Drain immediately while hasMore is true; otherwise wait a bounded time and poll again.

List results never contain payload bytes. Each event reports:

  • its team and optional project owner;
  • event type, source, environment, and creation time;
  • payloadAvailability;
  • replayableUntil when a retained payload remains replayable; and
  • metadataExpiresAt for the event record itself.

These timestamps are authoritative. Do not assume a fixed retention duration.

Retrieve payload bytes#

Retrieve metadata without content by default. Add includePayload=true to ask for the exact native webhook body:

cURL
curl "https://api.polymorfa.com/platform/projects/$PROJECT_ID/events/$EVENT_ID?includePayload=true" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
TypeScript
const event = await project.events.retrieve("<event-id>", { includePayload: true });

if (event.data.payload) {
  const body = JSON.parse(atob(event.data.payload.data));
  console.log(body);
}

When available and still authorized, payload contains base64-encoded bytes with encoding: "base64" and contentType: "application/json". Decode those bytes without parsing and reserializing them when you need the original body.

A null payload is not reconstructed from metadata. Check payloadAvailability and replayableUntil on every response. Disabling the content-retention grant for the exact source session makes its retained content unavailable immediately, even if its metadata remains visible.

Event metadata never includes signing secrets, authorization headers, cookies, raw network errors, or webhook response bodies.

Replay an event #

Replay creates a new logical delivery for one existing event and one webhook:

cURL
curl -X POST "https://api.polymorfa.com/platform/projects/$PROJECT_ID/events/$EVENT_ID/replays" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "webhookId": "'"$WEBHOOK_ID"'" }'
TypeScript
const replay = await project.events.replay(
  "<event-id>",
  { webhookId: "<webhook-id>" },
  { idempotencyKey: crypto.randomUUID() },
);

console.log(replay.data.deliveryId, replay.data.operationId);

Send webhookId in the JSON body and an Idempotency-Key header. For a team event, use API Replay team event. The route requires events:replay; it does not use the delivery-retry permission. The event and webhook must have the same owner, and the server rechecks payload availability in the mutation transaction.

The response immediately identifies the original event, the new delivery, the asynchronous operation, and the idempotency receipt. It does not wait for the network attempt to finish. If the exact body is unavailable or past replayableUntil, the request returns payload_not_replayable without creating a delivery.

Replay preserves the original event and every existing delivery. Use delivery retry when you need another attempt on an existing logical delivery.