openapi: 3.0.3
info:
  title: node-hp-scan-to scan event webhook
  description: |
    Outbound webhook contract of node-hp-scan-to. After a scan completes (or
    one of its deliveries fails), the CLI POSTs a JSON event to the URL
    provided by the integrator via `--webhook-url`.

    This document describes the request the consumer will receive: the exact
    endpoint path is whatever the integrator configured (the example
    `/webhook/scan` is only illustrative).

    Delivery is **best-effort**: one POST per event, with a 10 second timeout.
    Any `2xx` acknowledges the event; anything else (including a `3xx`, which
    is never followed) is logged and the event is not retried. Nothing is
    persisted, so a consumer that needs guaranteed delivery should put a queue
    in front of its endpoint.

    The payload has two profiles, selected with `--webhook-payload`:

    - `full` (default): everything below.
    - `minimal`: `metadata.device` and `metadata.target` are absent,
      `files[].path` is never sent and `delivery[].error` is replaced by
      `delivery failed (error redacted)` — no scanner IP, no printer
      destination label, no filesystem path, no internal host name from a
      failed upload. Settings, page and file descriptors, sizes, digests,
      store locations and delivery statuses are unchanged, so the consumer can
      still file the document.

    Every event carries an `idempotency-key` header (the event `id`), so a
    consumer can deduplicate a replay.

    The event is a metadata notification: delivering it never removes the scan.
    Retention follows the delivery targets and `--keep-files`, so a local
    `files[].path` may already be stale when the consumer handles the event.
  version: 1.0.0
  contact:
    name: node-hp-scan-to
    url: https://github.com/manuc66/node-hp-scan-to
paths:
  /webhook/scan:
    post:
      operationId: receiveScanEvent
      summary: Receive a scan-completed (or scan-delivery-failed) event
      description: |
        The URL is chosen by the consumer (`--webhook-url`); the path shown is
        an example. The client never expects a response body — any `2xx`
        acknowledges delivery.
      parameters:
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            const: application/json
          description: Always `application/json`.
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
            const: node-hp-scan-to
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            format: uuid
          description: |
            Event id, also present in the body. Consumers should deduplicate
            on it: the same event may be retried by the outbox.
        - name: X-Webhook-Signature
          in: header
          required: false
          schema:
            type: string
            description: |
              Hex HMAC-SHA256 of the raw request body when the webhook is
              configured with `--webhook-auth hmac`. The header name is
              configurable via `--webhook-auth-header` (default
              `x-webhook-signature`).
        - name: Authorization
          in: header
          required: false
          schema:
            type: string
          description: >
            Present instead of X-Webhook-Signature when `--webhook-auth` is
            `bearer` (`Bearer <token>`) or `basic` (`Basic base64(user:pass)`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScanEvent'
      responses:
        "2xx":
          description: Event acknowledged and removed from the outbox.
        "408":
          description: Retried later (transient timeout).
        "429":
          description: Retried later (rate limited).
        "5XX":
          description: Retried later (server error).
        "4XX":
          description: |
            Permanent rejection (anything else), the event is dead-lettered.
components:
  schemas:
    ScanEvent:
      type: object
      required: [id, type, time, metadata, pages, files, delivery]
      properties:
        id:
          type: string
          format: uuid
          description: Same value as the Idempotency-Key header.
        type:
          type: string
          enum: [scan-completed, scan-delivery-failed]
          description: |
            `scan-completed` when every delivery (paperless/nextcloud/s3/pdf)
            succeeded, `scan-delivery-failed` when at least one failed.
        time:
          type: string
          format: date-time
          description: ISO-8601 timestamp the event was created.
        metadata:
          $ref: '#/components/schemas/ScanMetadata'
        pages:
          type: array
          items:
            $ref: '#/components/schemas/WebhookPageDescriptor'
          description: One descriptor per scanned page (ADF pages are not necessarily all the same size).
        files:
          type: array
          items:
            $ref: '#/components/schemas/WebhookFileDescriptor'
          description: |
            One descriptor per file the event can point at. Empty when nothing
            is fetchable: the paperless PDF modes delete the pages they
            converted and the PDF they uploaded, so an event from those flows
            may describe no file at all.
        delivery:
          type: array
          items:
            $ref: '#/components/schemas/WebhookDeliveryTarget'
          description: Outcome of every upload attempt of this scan.
    ScanMetadata:
      type: object
      required: [command, scanCount, settings, startedAt, instance]
      properties:
        command:
          type: string
          enum: [single-scan, listen, adf-autoscan]
        scanCount:
          type: integer
          minimum: 0
          description: |
            Scan counter for the run: `0` for a single-scan, otherwise the scan
            number also used in the file name (`1` for the first scan of a
            listen/adf-autoscan session).
        device:
          allOf:
            - $ref: '#/components/schemas/ScanDeviceInfo'
          description: Absent in the `minimal` payload profile.
        target:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/ScanTargetInfo'
          description: Selected walkup-scan target, absent for single-scan and in the `minimal` payload profile.
        settings:
          $ref: '#/components/schemas/ScanSettingsInfo'
        startedAt:
          type: string
          format: date-time
        instance:
          $ref: '#/components/schemas/ScanInstanceInfo'
        job:
          allOf:
            - $ref: '#/components/schemas/ScanJobSummary'
          description: Device job summary, filled as scans run.
        endedAt:
          type: string
          format: date-time
          description: Filled in when the event is emitted.
        durationMs:
          type: integer
          description: Scan duration in ms (event emission time minus startedAt).
    ScanDeviceInfo:
      type: object
      required: [ip, isEscl]
      properties:
        ip:
          type: string
        isEscl:
          type: boolean
          description: True when the device was reached through the eSCL protocol.
    ScanTargetInfo:
      type: object
      required: [label, resourceURI]
      properties:
        label:
          type: string
          description: Human-readable destination label shown on the printer.
        resourceURI:
          type: string
          description: Stable device identifier of the destination.
    ScanSettingsInfo:
      type: object
      required:
        - inputSource
        - contentType
        - format
        - sourceFormat
        - mode
        - colorDepth
        - channels
        - resolution
        - isDuplex
        - pageCountingStrategy
      properties:
        inputSource:
          type: string
          enum: [Adf, Platen]
        contentType:
          type: string
          enum: [Document, Photo]
        format:
          type: string
          description: Format delivered to the target, e.g. `pdf` or `jpg`.
        sourceFormat:
          type: string
          description: Format requested to the device, e.g. `jpg` (may differ after compression).
        mode:
          type: string
          enum: [Gray, Color, Lineart]
        colorDepth:
          type: integer
          description: Bits per channel (8 for Color/Gray, 1 for Lineart).
        channels:
          type: integer
          description: 3 for Color, 1 otherwise.
        resolution:
          type: integer
          description: DPI.
        isDuplex:
          type: boolean
        duplexMode:
          type: string
          enum: [Simplex, Duplex, FrontOfDoubleSided, BackOfDoubleSided]
        targetDuplexMode:
          type: string
          enum: [Simplex, Duplex, EmulatedDuplex]
        duplexAssemblyMode:
          type: string
          enum: [page-wise, document-wise, reverse-front, reverse-both]
        pageCountingStrategy:
          type: string
          enum: [Normal, "Odd Only", "Even Only"]
        paperSize:
          type: string
          nullable: true
        paperDim:
          type: string
          nullable: true
          description: Explicit paper dimensions when known, e.g. `21x29.7cm`.
    ScanInstanceInfo:
      type: object
      required: [id, startedAt]
      properties:
        id:
          type: string
          description: Random id generated once per running CLI process.
        startedAt:
          type: string
          format: date-time
    ScanJobSummary:
      type: object
      required: [state, count]
      properties:
        state:
          $ref: '#/components/schemas/JobState'
        count:
          type: integer
          description: |
            Number of device jobs that produced the scan, not the number of
            pages: a 3-page ADF scan is one job and reports `count: 1`. It is
            above 1 when several device jobs make up one scan, such as a
            multi-page platen session (one job per page) or an emulated duplex
            scan (a front pass and a back pass). The page count is the length of
            the event's `pages` array.
    JobState:
      type: string
      enum: [Completed, Processing, Canceled, Blocked]
    WebhookPageDescriptor:
      type: object
      required: [pageNumber, format, width, height, xResolution, yResolution]
      properties:
        pageNumber:
          type: integer
          description: 1-based page position in the scan (interleaved for emulated duplex).
        format:
          type: string
          description: Extension without the dot, e.g. `jpg`.
        width:
          type: integer
        height:
          type: integer
        xResolution:
          type: integer
          description: Horizontal DPI.
        yResolution:
          type: integer
          description: Vertical DPI.
        sizeBytes:
          type: integer
          description: File size in bytes when it could be read.
    WebhookFileDescriptor:
      type: object
      required: [name, size, sha256, format]
      properties:
        name:
          type: string
          description: Base file name.
        path:
          type: string
          description: |
            Local path, only present when the file is stored locally. May be
            cleaned up after successful delivery (unless `--keep-files` is
            set); never exposed for remote stores, and never sent at all in the
            `minimal` payload profile.
        size:
          type: integer
          description: File size in bytes at event creation.
        sha256:
          type: string
          description: Hex SHA-256 of the file content at event creation.
        format:
          type: string
          description: Extension without the dot, e.g. `pdf`.
        contentType:
          type: string
          nullable: true
        store:
          type: string
          enum: [local, s3, nextcloud]
          description: Where the file actually lives when the event was created.
        location:
          allOf:
            - $ref: '#/components/schemas/WebhookFileLocation'
          description: How to reach the object; always set when store is not `local`.
    WebhookFileLocation:
      type: object
      properties:
        bucket:
          type: string
          description: S3 bucket when store is `s3`.
        key:
          type: string
          description: S3 object key when store is `s3`.
        webdavUrl:
          type: string
          description: WebDAV URL of the file when store is `nextcloud`.
    WebhookDeliveryTarget:
      type: object
      required: [target, status]
      properties:
        target:
          type: string
          description: e.g. `paperless`, `nextcloud`, `s3`, `pdf`.
        status:
          type: string
          enum: [success, failed]
        error:
          type: string
          nullable: true
        references:
          type: array
          items:
            type: string
          description: |
            Identifiers the target returned for what it accepted, so the
            consumer can find the document even when no local file is left:

            - `paperless`: the task ids (UUIDs), usable with
              `GET /api/tasks/?task_id=...` — one per created document;
            - `nextcloud`: the WebDAV URL of every uploaded file;
            - `s3`: `bucket/key` of every uploaded object;
            - `pdf`: absent, the local file is already described in `files[]`.

            Absent when the target returned nothing usable, and on failure.