Receive proactive notifications via polling

Poll the events endpoint on your own schedule to retrieve system-initiated messages that have been routed to CAPI users. Polling is the recommended path when an inbound HTTPS receiver isn’t viable on your backend, and the source of truth for reconciling events after a webhook outage. If you can run an inbound receiver, prefer outbound webhook push for lower latency to your users and lower load on Moveworks.

Before reading this page, review Proactive notifications overview for architecture, routing behavior, and prerequisites.

The events endpoint

Retrieve system-initiated messages for a user:

$
curl "https://api.moveworks.ai/assistant/v1/conversations/-/events?starting_after=<YOUR_CHECKPOINT>" \
>
  -H "Authorization: Bearer <MW_ACCESS_TOKEN>" \
>
  -H "Assistant-Name: <YOUR_BOT_NAME>"

Substitute:

• <YOUR_CHECKPOINT> — the event_id you last successfully processed for this user. Passed as starting_after (exclusive lower bound). Omit on the first-ever call for a user.
• <MW_ACCESS_TOKEN> — a valid Moveworks bearer token for the recipient user. See the auth guides for token issuance.
• <YOUR_BOT_NAME> — the Bot Name provided by your account team.

The - in the URL is a wildcard that returns events across all of the user’s conversations, including new conversations Moveworks created for proactive messages with no prior user input.

Query parameters

When both starting_after and ending_at are supplied, ending_at must refer to an event created after the one identified by starting_after.

Response

1
{
2
  "events": [
3
    {
4
      "event_id": "evt_340xdCuTfBHbSriGYQz6J",
5
      "conversation_id": "conv_340xdCMeTfceLCg8Gt6LP",
6
      "created_at": "2026-08-03T22:03:22.965068Z",
7
      "event_payload": {
8
        "type": "MESSAGE_EVENT",
9
        "message": {
10
          "message_id": "msg_340xdCrqXA6LvcoIgVbfs",
11
          "conversation_id": "conv_340xdCMeTfceLCg8Gt6LP",
12
          "response_id": "resp_340xdCMeTfceLCg0s1LRL",
13
          "actor": "ASSISTANT",
14
          "content": {
15
            "type": "MARKDOWN_TEXT",
16
            "markdown_text": { "text": "Reminder: Your password expires in 3 days." }
17
          },
18
          "created_at": "2026-08-03T22:03:22.965068Z"
19
        }
20
      }
21
    }
22
  ],
23
  "metadata": {}
24
}

Response fields

The events endpoint returns only final messages; intermediate reasoning or in-progress states are not included.

Scope. The events endpoint is scoped to a single user, consistent with all other Conversations API endpoints. Polling and recovery must be performed per user using each user’s stored last_event_id.

Response headers. Every response includes an x-trace-id header identifying the request. Capture it if you need to correlate to Moveworks-side logs when opening a support case. The legacy x-moveworks-root-uuid header is also returned for backward compatibility but is deprecated; prefer x-trace-id.

Recommended pattern: per-user checkpoint

Advancing through the event stream requires tracking your position per user. Maintain a {user_id, last_event_id} record per user in your backend and pass last_event_id as starting_after on each poll.

Event IDs are base-62 identifiers with an evt_ prefix, consistent with other Conversations API resource IDs. Use each processed event’s ID as your next cursor value for exact iteration through the stream.

The same checkpoint pattern underlies webhook-based delivery — see Per-user checkpoint on the outbound webhook page.

Recovery after an outage

If your backend was unavailable when new events were created, call the events endpoint per affected user using that user’s stored checkpoint:

$
curl "https://api.moveworks.ai/assistant/v1/conversations/-/events?starting_after=<USER_CHECKPOINT>" \
>
  -H "Authorization: Bearer <MW_ACCESS_TOKEN>" \
>
  -H "Assistant-Name: <YOUR_BOT_NAME>"

Omit ending_at to fetch all events since the checkpoint up to the present. Paginate using next_cursor if the result set exceeds one page.

Testing end-to-end

Because of the routing behavior, testing requires establishing the CAPI integration as the recipient’s most-recent-interaction channel before triggering the source-system webhook.

$
# 1. Create a conversation
$
curl -X POST "https://api.moveworks.ai/assistant/v1/conversations" \
>
  -H "Authorization: Bearer <MW_ACCESS_TOKEN>" \
>
  -H "Assistant-Name: <YOUR_BOT_NAME>" \
>
  -H "Content-Type: application/json" \
>
  -d '{"title":"pre-interaction for proactive test"}'
$
$
# 2. Send a user message. This returns 202 with status IN_PROGRESS.
$
curl -X POST "https://api.moveworks.ai/assistant/v1/conversations/<CONV_ID>/responses" \
>
  -H "Authorization: Bearer <MW_ACCESS_TOKEN>" \
>
  -H "Assistant-Name: <YOUR_BOT_NAME>" \
>
  -H "Content-Type: application/json" \
>
  -d '{"input":{"text":"hello"}}'
$
$
# 3. Poll the response until status becomes COMPLETED before proceeding.
$
curl "https://api.moveworks.ai/assistant/v1/conversations/<CONV_ID>/responses/<RESP_ID>" \
>
  -H "Authorization: Bearer <MW_ACCESS_TOKEN>" \
>
  -H "Assistant-Name: <YOUR_BOT_NAME>"

$
curl -i -X POST "<YOUR_LISTENER_URL>" \
>
  -H "Content-Type: application/json" \
>
  -d '<YOUR_TEST_PAYLOAD>'

$
curl "https://api.moveworks.ai/assistant/v1/conversations/-/events" \
>
  -H "Authorization: Bearer <MW_ACCESS_TOKEN>" \
>
  -H "Assistant-Name: <YOUR_BOT_NAME>"

Common test failures and diagnostic paths

Related

• Proactive notifications overview
• Receive via outbound webhook
• Agent Studio Webhook Triggers Quickstart