openapi: 3.2.0
info:
  title: Hookbase Realtime API
  version: 1.0.0
  description: Official OpenAPI 3.0 specification for the Hookbase webhook relay platform. Generated from the maintained Postman collection. Authenticate with an API key (whr_ prefix) as a Bearer token.
  contact:
    name: Hookbase
    url: https://www.hookbase.app
servers:
- url: https://api.hookbase.app
  description: Production
security:
- bearerAuth: []
tags:
- name: Realtime
paths:
  /api/realtime/stream:
    get:
      tags:
      - Realtime
      summary: Stream events
      operationId: realtime_stream_events
      parameters:
      - name: sourceId
        in: query
        required: false
        schema:
          type: string
        example: src_abc123
        description: Filter by source ID or slug. A slug that matches no source returns 404.
      responses:
        '200':
          description: Successful response
          content:
            text/event-stream: {}
      description: Server-Sent Events (SSE) stream of live inbound events and deliveries for the organization (event_received, delivery_started/completed/failed/throttled, source_rate_limited). EventSource can't set headers, so the API key may be passed as ?token= instead of Authorization. The connection is held open for ~25 seconds and then closes with a `reconnect` event; reconnect with the `Last-Event-ID` header (or the resume timestamp from that event) to continue without gaps. For a one-shot fetch instead of a live connection, use GET /api/realtime/recent.
  /api/realtime/recent:
    get:
      tags:
      - Realtime
      summary: Get recent events
      operationId: realtime_get_recent_events
      parameters:
      - name: sourceId
        in: query
        required: false
        schema:
          type: string
        example: src_abc123
        description: Filter by source ID or slug. A slug that matches no source returns 404.
      - name: limit
        in: query
        required: false
        schema:
          type: string
        example: '20'
      responses:
        '200':
          description: Successful response
      description: Snapshot of recent events and their deliveries, for initial load before opening the /stream SSE connection (or for polling clients that don't need push).
  /api/realtime/outbound-stream:
    get:
      tags:
      - Realtime
      summary: Stream outbound messages
      operationId: realtime_stream_outbound_messages
      parameters:
      - name: applicationId
        in: query
        required: false
        schema:
          type: string
        example: app_abc123
      - name: endpointId
        in: query
        required: false
        schema:
          type: string
        example: ep_abc123
      responses:
        '200':
          description: Successful response
          content:
            text/event-stream: {}
      description: Server-Sent Events (SSE) stream of live outbound webhook message and delivery-attempt events for the organization (message_queued/processing/succeeded/failed/exhausted, attempt_started/completed). Same auth (?token= supported), 25-second connection, and Last-Event-ID reconnect contract as GET /api/realtime/stream.
  /api/realtime/outbound-recent:
    get:
      tags:
      - Realtime
      summary: Get recent outbound messages
      operationId: realtime_get_recent_outbound_messages
      parameters:
      - name: applicationId
        in: query
        required: false
        schema:
          type: string
        example: app_abc123
      - name: endpointId
        in: query
        required: false
        schema:
          type: string
        example: ep_abc123
      - name: limit
        in: query
        required: false
        schema:
          type: string
        example: '20'
      responses:
        '200':
          description: Successful response
      description: Snapshot of recent outbound messages and delivery attempts, for initial load before opening the /outbound-stream SSE connection.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Hookbase API key with the whr_ prefix.