Real-time notification stream (SSE)

GET /v1/me/notifications/stream pushes each new in-app Notification row to
connected clients as soon as it is persisted, without polling. Use this endpoint
when the app is foregrounded so travelers see disruption alerts instantly.
Every frame carries a cursor, so a client that reconnects picks up exactly
where it left off.

Authentication

Same requirement as all other /v1 endpoints: sign the request with the
consumer HMAC and pass a valid traveler JWT in the
Authorization: Bearer <token> header.

A missing or invalid token returns 401.

Protocol

The endpoint uses Server-Sent Events (text/event-stream). Clients should:

1. Open the connection with Accept: text/event-stream (most SSE client
   libraries set this automatically).
2. Handle each event named notification as it arrives, and remember its
   id.
3. Reconnect automatically when the connection closes, sending the last id
   received as Last-Event-ID — use a fixed back-off strategy. See
   Reconnect and replay.

GET /v1/me/notifications/stream HTTP/1.1
Authorization: Bearer <token>
Accept: text/event-stream

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache

Client-library examples

The raw HTTP shape above works with any SSE-capable client. Most stacks have
a dedicated client library so you do not have to parse event:/data:
frames by hand.

Python (httpx-sse)

import httpx
from httpx_sse import connect_sse

with httpx.Client(
    base_url="https://api.travel.tech",
    headers={
        "Authorization": f"Bearer {traveler_jwt}",
        "TravelTech-Consumer": consumer,
        "TravelTech-Timestamp": timestamp,
        "TravelTech-Signature": signature,
    },
) as client:
    with connect_sse(client, "GET", "/v1/me/notifications/stream") as event_source:
        for sse in event_source.iter_sse():
            if sse.event == "notification":
                last_event_id = sse.id  # send as Last-Event-ID on reconnect
                notification = sse.json()
                print(notification["title"], notification["body"])
            elif sse.event == "done":
                break  # server is shutting down; reconnect with backoff

httpx-sse raises on a non-2xx response before any event is read, so a
401 from a missing or invalid token surfaces as an exception rather than
silently yielding zero events. httpx-sse does not reconnect for you: when you
open the next connection, add "Last-Event-ID": last_event_id to its headers.

TypeScript / JavaScript (browser EventSource)

Native EventSource cannot set the Authorization header the consumer
HMAC and bearer credentials need, so most browser clients instead use a
library that supports custom headers, such as
@microsoft/fetch-event-source.
It sends Last-Event-ID on each reconnect by itself:

import { fetchEventSource } from "@microsoft/fetch-event-source";

await fetchEventSource("https://api.travel.tech/v1/me/notifications/stream", {
  headers: {
    Authorization: `Bearer ${travelerJwt}`,
    "TravelTech-Consumer": consumer,
    "TravelTech-Timestamp": timestamp,
    "TravelTech-Signature": signature,
  },
  onmessage(msg) {
    if (msg.event === "notification") {
      const notification = JSON.parse(msg.data);
      console.log(notification.title, notification.body);
    } else if (msg.event === "done") {
      throw new Error("stream closing"); // triggers the library's own retry
    }
  },
  onerror(err) {
    console.error("notification stream error", err);
    // rethrow to stop retrying, or return to let the library back off and reconnect
  },
});

Event format

notification — new in-app row

Emitted for every new streamable Notification row persisted for the
authenticated traveler (see Inbox-only by design for
the ones that are not). The data field is a JSON-serialised
NotificationOut object
(the same shape returned by GET /v1/me/notifications).

The id field is an opaque cursor. Store the last one you receive and send it
back on reconnect; do not parse it or build one yourself.

id: AQAGUqHcVHoAAY8sPhI0eryN7wAAAAAAAQ
event: notification
data: {"id":"...","event_type":"segment.delayed","severity":"warning","title":"Delay — Flight","body":"Your trip is delayed by 45m.",...}

event_type is always the dotted wire value — segment.delayed,
booking_lifecycle.confirmed, leg.fields_updated, assistant_reply. It is
the same string the push notification carries in its payload metadata and the
same string GET /v1/me/notifications returns, so a client can branch on one
value regardless of how the notification reached it. See
Event types for every value the stream can deliver; the API
reference for this endpoint shows one complete example frame per value.

done — stream closing

Emitted when the server initiates a graceful shutdown. After receiving this
event the client should reconnect if it still needs real-time delivery.

event: done
data: {}

Example payload

{
  "id": "00000000-0000-4000-8000-000000000006",
  "trip_id": "00000000-0000-4000-8000-0000000000a1",
  "segment_id": "00000000-0000-4000-8000-0000000000b1",
  "event_type": "segment.delayed",
  "severity": "warning",
  "title": "Delay — Flight",
  "body": "Your trip is delayed by 45m.",
  "deep_link": "bizaway://trips/00000000-0000-4000-8000-0000000000a1?segment=00000000-0000-4000-8000-0000000000b1",
  "channel": "push",
  "dispatched_at": "2026-11-03T07:40:00Z",
  "read_at": null,
  "is_dedup_skipped": false,
  "delivery_status": "pending",
  "created_at": "2026-11-03T07:40:00Z"
}

Payload fields

Every notification event carries the same NotificationOut object,
whatever its event_type. There is no per-event payload: the event-specific
detail is already rendered into title and body, and deep_link points to
the screen that shows the rest.

Event types

The stream delivers every notification travel.tech raises for a traveler's
trips, bookings, assistant conversations, and Tasks, except the ones listed
under Inbox-only by design. Severity is the default.
A strike-related event (segment.at_risk, segment.disrupted,
segment.cancelled, or segment.delayed) is always critical, whatever its
default.

Trip segments (segment.*)

Raised when a booked flight, train, stay, or car segment changes status.

Live journey details (leg.*)

Booking lifecycle (booking_lifecycle.*)

Raised when a booking changes state. segment_id is null; trip_id is set
when the booking already belongs to a trip.

Assistant replies and Tasks

Inbox-only by design

These notifications are delivered to the inbox only, by design. They appear in
GET /v1/me/notifications; read the inbox to show them:

• Pre-trip briefings (pre_trip_briefing.stay, pre_trip_briefing.train,
  pre_trip_briefing.car).
• Destination advisories (info_surface.destination_advisory).
• Travel-policy notices (selection_policy, policy_notify,
  policy_approval_requested, policy_approval_decided).
• Scheduled reminders, such as check-in reminders.
• Notifications grouped into a batch when several updates hit the same
  segment in a short window, and duplicates (is_dedup_skipped: true).

Treat unknown event_type values as generic notifications: render title
and body, and follow deep_link. New values may be added without notice.

Reconnect and replay

A stream can be served by any travel.tech server, and every stream receives
every streamable notification for its traveler, whichever server created it.

When the connection drops, reconnect and send the id of the last
notification frame you received:

• in the Last-Event-ID header — SSE client libraries that reconnect for you
  send it automatically; or
• as the since query parameter, GET /v1/me/notifications/stream?since=<id>,
  for clients that cannot set the header. If both are sent, the header wins.

The stream first replays every streamable notification created after that
cursor, oldest first, then continues live. A connection opened without a cursor
starts live, and first re-sends the streamable notifications from the last 30
seconds, so one created while you were opening the stream is not lost. Those
may already be in your inbox; de-duplicate them by data.id.

A cursor that the stream did not issue is rejected with 422; reconnect
without it and catch up from the inbox.

Recommended client strategy:

• Persist the last id and reconnect with it after every disconnect, including
  after event: done.
• De-duplicate by the notification's data.id when you merge stream events
  with rows read from GET /v1/me/notifications.
• The inbox stays authoritative. On a cold start, after a long time offline, or
  when you have no cursor, read GET /v1/me/notifications, then open the
  stream without a cursor.

Relationship to push notifications

When the app is connected via SSE, the client should suppress local push
notification UI for events it receives via the stream to avoid double-alerting
the traveler. The push notification is still sent; the client decides at
render time whether to display it based on SSE connection state.

Error responses

Reporting issues

This page is maintained by the BizAway integration team. To request changes or
report an error, contact your BizAway integration contact. Edits made directly
in the ReadMe dashboard are overwritten on the next publish.