Change Broker update workflow

Use this workflow to implement continuous update retrieval for a client application that has already completed the configuration workflow. This flow reads change data in order, keeps your bookmark cursor current, and recovers from expiration without losing your read position. After completing a full iteration, your client application is ready to repeat the loop for ongoing ingestion.

Note: Before starting this workflow, your client application must have an active signup and a valid starting bookmark. If you have not yet completed signup setup, see Change Broker configuration workflow.

Prerequisites

• Your signup is in an Active state.

• Your client application holds a valid bookmark obtained from a Get signup by ID response.

• Your client application can persist bookmark values between application restarts.

• The identity querying updates is the signup owner.

1. Retrieve updates

This phase reads the next page of change data for the signup, advancing your read position and returning a renewed bookmark for the following request.

1. Load persisted bookmark from your application's bookmark store.

   On first run, use the bookmark obtained from the Get signup by ID response. On subsequent runs, use the bookmark from the most recent successful Get updates response.

2. Get updates (current bookmark) using the Get updates endpoint. Submit a request with the loaded bookmark.

   A successful request returns 200 OK with a page of change data and a renewed bookmark token. Process and persist the returned change data first, then persist the renewed bookmark only after processing succeeds. This sequence allows safe retry with the prior bookmark if ingestion fails before processing completes.

3. Immediately request next page if the response page is at or near the 100,000 transaction target.

   The system continues to return pages of change events and a renewed bookmark for each request. Continue repolling until the response page size drops below the 100,000 transaction level. This prevents ingest from outpacing reads during high-volume periods.

2. Handle an expired bookmark

This phase recovers your read position when a bookmark has expired and [Get updates](getUpdates) returns a 400 Bad Request response.

4. Get signup by ID using the [Get signup by ID](getSignup) endpoint. Retrieve the signup to obtain the renewed bookmark from bookmarkInfo.bookmark, then persist it.

   The system returns the signup details including the renewed bookmark in bookmarkInfo.bookmark. Persist this bookmark immediately.

5. Resume update loop using the renewed bookmark.

   The renewed bookmark starts from the earliest available change data from when the renewed bookmark was provided, not from where the expired bookmark left off.

After each full iteration, repeat from phase 1 to continue ingestion.

Next steps

• For polling cadence, payload size tuning, and bookmark best practices, see Change Broker best practices.

• For ongoing issues with lag, payload growth, or bookmark convergence, see Change Broker troubleshooting.