Real-Time Notifications API

Real-time event notifications over WebSocket. The API maintains a persistent connection from your client and pushes JSON messages whenever an event on your watchlist has a relevant change — stock updates, price movements, new sections becoming available. There is no polling endpoint; everything flows through the streaming connection.

1. Base URL

wss://api.eventory.ai/eventory

TLS is required. ws:// is not accepted.

2. Authentication

Pass your API key in the apikey HTTP header on the WebSocket upgrade request:

apikey: YOUR_API_KEY

The key is sent only on the upgrade. Once the WebSocket is open, no further authentication is required. The gateway strips the credential before forwarding internally; downstream services never see it.

3. Endpoints

Health check

GET https://api.eventory.ai/eventory/ping

Subscribe

GET /notifications/subscribe

GET /notifications/subscribe/filtered

Both endpoints upgrade the request to a WebSocket and push the same JSON message envelope (see §4). They differ only in how much filtering the server applies before delivery — see §6.

4. Message Format

Every message is a JSON text frame with this envelope:

{
  "timestamp": "2026-04-27T10:00:00Z",
  "website": "ticketmaster",
  "version": "1.0",
  "event_id": "abc123",
  "region": "US",
  "changes": { "stock_increase": ["Floor GA", "Section 101"] },
  "sections_type": "OfferSections",
  "sections": { ... },
  "stock": 42,
  "event_infos": { ... }
}

changes field

changes is an object, not an array. Keys are change-type identifiers; values are arrays of section names affected by that change type.

"changes": {
  "stock_increase": ["Floor GA", "Section 101"],
  "price_decrease": ["Section 207"]
}

Common change types: stock_increase, price_decrease, price_increase.

event_infos object

Optional. Present when the platform exposes event metadata; otherwise omitted from the envelope entirely. Always check the field exists before reading any sub-field.

{
  "event_name": "Artist World Tour",
  "event_date": "2026-06-15T20:00:00Z",
  "event_time": "20:00",
  "event_venue": "Madison Square Garden",
  "event_venue_url": "https://...",
  "event_artist_name": "Artist",
  "event_location": "New York, NY",
  "event_url": "https://...",
  "event_image": "https://..."
}

All sub-fields may be empty strings depending on the source platform.

5. Section Types

The sections_type field determines the shape of sections. Two values are supported.

5.1 OfferSections

Flat map keyed by offer/section ID. Used by platforms with simple ticket tiers (e.g. "General Admission", "VIP", "Early Bird").

{
  "sections_type": "OfferSections",
  "sections": {
    "floor-ga": {
      "offer_name": "Floor GA",
      "available": true,
      "price": 129.50,
      "price_label": "$129.50",
      "stock": 12,
      "atc": "https://..."
    }
  }
}

5.2 SeatMapSections

Nested map. Each top-level key is a section ID. Inside each section, the stock key is the section-level aggregate, and every other key is an offer ID mapping to a SectionDetail object. Used by platforms that expose a full venue seat map (e.g. Ticketmaster, AXS).

{
  "sections_type": "SeatMapSections",
  "sections": {
    "sec-101": {
      "stock": 5,
      "offer-abc": {
        "offer_name": "Standard",
        "price": 95.00,
        "price_without_fees": 79.00,
        "price_label": "$95.00",
        "section": "101",
        "inventory_type": "primary",
        "is_active": true,
        "stock": 5,
        "stock_not_available": 2,
        "atc": "https://...",
        "longest_adjacent_seats": 3,
        "general_admission": false
      }
    }
  }
}

Section wrapper:

Offer (SectionDetail):

Dispatch on sections_type with a switch so each handler receives the correctly shaped data.

6. Server-Side Filtering

Filtering behavior depends on the endpoint you connect to.

/notifications/subscribe

The server applies exactly two filters before forwarding a notification:

1. Event membership. The notification's event_id must appear in your watchlist. Otherwise dropped.

2. Change-type match. Each watchlist entry has an optional change_type field (default "stock_increase"). The notification's changes object must contain a key matching that change type. Otherwise dropped.

No other watchlist field is enforced server-side on this endpoint. If your watchlist entry sets any of the following, your client is responsible for honoring them:

• min_price_filter, max_price_filter

• stock_threshold_filter

• seat_quantity

• section

• keywords

• standard_tickets, resale_tickets, general_admission_tickets, platinum_tickets

• date_filter

• row_filter

• muted_until

/notifications/subscribe/filtered

This endpoint delivers notifications that have already been filtered upstream against the full watchlist entry — every field listed above is applied for you. You receive only notifications that match your saved filters; no additional client-side filtering against the watchlist is required.

7. Anti-Spam (Cooldown)

Duplicate notifications are suppressed for 15 minutes. If nothing meaningful has changed about an offer in that window, you will not see a duplicate. After 15 minutes, the next matching change is delivered.

This deduplication is keyed on the notification content (event, region, sections, changed sections, total stock) plus your client identity. Multiple connections sharing the same identity share dedup state.