openapi: 3.1.0
info:
  title: Highlight OTLP Logs Webhooks API
  description: 'Native OpenTelemetry Protocol (OTLP) HTTP/JSON ingestion endpoint for structured logs. Accepts standard `ExportLogsServiceRequest` payloads. Logs are stored in ClickHouse for sub-second full-text search and pattern detection in the Highlight dashboard.

    '
  version: '1.0'
  contact:
    name: Highlight Support
    url: https://www.highlight.io/community
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://otel.highlight.io
  description: Highlight hosted OTLP collector
- url: http://localhost:4318
  description: Self-hosted OTLP collector (Hobby / Enterprise)
tags:
- name: Webhooks
  description: Inbound webhook delivery from Highlight
paths:
  /:
    post:
      summary: Receive Highlight Alert Webhook
      description: 'Delivered when an alert subscription matches. The customer endpoint should validate the optional shared-secret header (planned) and respond with `2xx` within 10 seconds to avoid retries.

        '
      operationId: receiveHighlightAlertWebhook
      tags:
      - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertWebhookPayload'
      responses:
        '200':
          description: Webhook acknowledged.
        '202':
          description: Webhook accepted for asynchronous processing.
        4XX:
          description: Webhook rejected.
        5XX:
          description: Receiver error; Highlight will retry per its delivery policy.
components:
  schemas:
    AlertWebhookPayload:
      type: object
      description: 'Payload sent for alert webhook deliveries.

        '
      required:
      - Event
      - AlertName
      - ProjectID
      properties:
        Event:
          type: string
          description: Alert event type.
          enum:
          - ERRORS_ALERT
          - NEW_USER_ALERT
          - USER_PROPERTIES_ALERT
          - TRACK_PROPERTIES_ALERT
          - SESSION_FEEDBACK_ALERT
          - NEW_SESSION_ALERT
          - RAGE_CLICK_ALERT
          - METRIC_MONITOR
          - LOG_ALERT
          - TRACE_ALERT
        AlertName:
          type: string
          description: Human-readable alert name.
        AlertID:
          type: integer
          description: Numeric identifier for the alert subscription.
        ProjectID:
          type: integer
          description: Numeric Highlight project ID.
        WorkspaceID:
          type: integer
        Count:
          type: integer
          description: Number of matching errors/sessions in the alert window.
        Threshold:
          type: integer
          description: Alert threshold count.
        ErrorTitle:
          type: string
          description: Present on ERRORS_ALERT events.
        ErrorURL:
          type: string
          format: uri
        ErrorResolvedURL:
          type: string
          format: uri
          description: Action URL to mark the error resolved.
        ErrorIgnoredURL:
          type: string
          format: uri
          description: Action URL to ignore the error.
        ErrorSnoozedURL:
          type: string
          format: uri
          description: Action URL to snooze the error.
        SessionID:
          type: string
        SessionSecureID:
          type: string
        SessionURL:
          type: string
          format: uri
        SessionIdentifier:
          type: string
          description: Identifier supplied via `H.identify`.
        UserIdentifier:
          type: string
        UserProperties:
          type: object
          additionalProperties: true
        TrackProperties:
          type: object
          additionalProperties: true
        Query:
          type: string
          description: Filter expression that triggered the alert.
        Timestamp:
          type: string
          format: date-time