Notifications

How Openavail delivers event notifications back to agents.

What triggers a notification

Notifications are sent to the affected party, not the agent that initiated the action.

Event	Who gets notified
booking.displaced	The agent whose booking was preempted
hold.expired	The agent that created the hold
booking.cancelled	The agent that created the booking

A direct booking produces no notification for the creating agent — they initiated it, so there is nothing to tell them.

The pending envelope

Every side-effect response (POST /v1/availability/search, POST /v1/bookings, POST /v1/bookings/{hold_id}/confirm) includes a pending_notifications field in the response body. This is the primary delivery channel.

{
  "booking_id": "…",
  "correlation_id": "…",
  "pending_notifications": [
    {
      "id": "3839ca7d-…",
      "kind": "hold.expired",
      "payload": {
        "hold_id": "cb16c8e0-…",
        "start": "2026-05-22T11:00:00.000Z",
        "end": "2026-05-22T12:00:00.000Z",
        "reason_code": "expired"
      },
      "created_at": "2026-05-22T10:45:46.111Z"
    }
  ]
}

Notifications are marked delivered at this point and will not appear again.

Pull endpoint

Agents that want to check their queue without making a side-effect request can use:

GET /v1/notifications/pending
Authorization: Bearer <api-key>

This returns all undelivered notifications without marking them delivered. Calling it repeatedly returns the same list until the agent's next action response drains it.

Use this endpoint for:

• Debugging: inspect what is waiting before making the next call.
• Long-running agents that may not call a side-effect endpoint frequently.

Delivery semantics

• Notifications accumulate between action calls.
• They drain (are marked delivered) on the next side-effect response, not on GET /v1/notifications/pending.
• A notification that is never drained — because the agent never makes another action call — is automatically swept after 7 days.

Payload redaction

Agents without the read_events permission receive a reduced payload. Fields that could expose event titles or attendees are stripped. The fields always present regardless of permission level are:

Field	Always visible
hold_id	Yes
start	Yes
end	Yes
reason_code	Yes

To receive the full payload (including booking titles and attendee context), grant the agent the read_events permission in the agent registry.