openapi: 3.0.3
info:
  title: Webhook Relay API Data Model
  version: 2026.07.31
  description: First-party starter OpenAPI for relay ingress and delivery status (CC BY 4.0). Desk composite — not a vendor SLA.
  contact:
    name: InfiniSynapse Data Team
    url: https://infinisynapse.com/en/editorial-standards#data-team
servers:
  - url: https://relay.example.com
paths:
  /v1/events:
    post:
      summary: Ingest a vendor or internal event
      operationId: ingestEvent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RelayEventIn'
      responses:
        '202':
          description: Accepted and persisted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelayEvent'
  /v1/events/{id}:
    get:
      summary: Lookup event by id
      operationId: getEvent
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelayEvent'
  /v1/deliveries:
    get:
      summary: List deliveries by state
      operationId: listDeliveries
      parameters:
        - in: query
          name: state
          schema: { type: string, enum: [pending, delivering, delivered, failed, dead_letter] }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Delivery'
  /v1/endpoints:
    post:
      summary: Register customer endpoint
      operationId: createEndpoint
      responses:
        '201':
          description: Created
components:
  schemas:
    RelayEventIn:
      type: object
      required: [source, type, idempotency_key, payload]
      properties:
        source: { type: string }
        type: { type: string }
        idempotency_key: { type: string }
        payload: { type: object, additionalProperties: true }
    RelayEvent:
      allOf:
        - $ref: '#/components/schemas/RelayEventIn'
        - type: object
          properties:
            id: { type: string, format: uuid }
            received_at: { type: string, format: date-time }
            payload_hash: { type: string }
    Delivery:
      type: object
      properties:
        id: { type: string, format: uuid }
        event_id: { type: string, format: uuid }
        endpoint_id: { type: string, format: uuid }
        state: { type: string }
        attempt_count: { type: integer }
        next_attempt_at: { type: string, format: date-time }