Blues Webhook API

openapi: 3.2.0
info:
  contact:
    email: engineering@blues.io
    name: Blues Engineering
    url: https://dev.blues.io/support/
  description: The OpenAPI definition for the Notehub.io API.
  title: Notehub Webhook API
  version: 1.2.0
servers:
- description: Production server
  url: https://api.notefile.net
tags:
- description: Webhook APIs for non-notecard event ingestion
  name: Webhook
paths:
  /v1/products/{productUID}/devices/{deviceUID}/webhook-event:
    post:
      operationId: CreateLegacyWebhookEvent
      description: Legacy endpoint for sending an event from a webhook, associated with the given device (provisioning it if necessary). The request body is a Note-shaped object containing the notefile name, body, and optional payload.
      parameters:
      - $ref: '#/components/parameters/productUIDParam'
      - $ref: '#/components/parameters/deviceUIDParam'
      requestBody:
        description: A Note-shaped event. Typically contains the notefile name (file), a JSON body, and an optional base64-encoded payload, but any additional Note fields (e.g. when, sn, where_lat, where_lon) are accepted and honored.
        required: true
        content:
          application/json:
            example:
              body:
                key: value
              file: data.qo
              payload: SGVsbG8sIFdvcmxkIQ==
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Event created successfully
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - personalAccessToken: []
      tags:
      - Webhook
      x-custom-attributes:
        permission: create
        resource: blues:resources:app:APPSERIAL:notes
      summary: Create legacy webhook event
      x-summary-source: derived
  /v1/products/{productUID}/devices/{deviceUID}/webhook-session:
    put:
      operationId: UpdateLegacyWebhookSession
      description: Legacy endpoint for opening or updating a webhook session for the given device (provisioning the device if necessary). Used by external services that need to maintain a callable session against a device behind a webhook.
      parameters:
      - $ref: '#/components/parameters/productUIDParam'
      - $ref: '#/components/parameters/deviceUIDParam'
      requestBody:
        description: Optional session metadata.
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Webhook session updated successfully
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - personalAccessToken: []
      tags:
      - Webhook
      x-custom-attributes:
        permission: create
        resource: blues:resources:app:APPSERIAL:notes
      summary: Update legacy webhook session
      x-summary-source: derived
  /v1/products/{productUID}/webhooks/{webhookUID}/devices/{deviceUID}/event:
    post:
      operationId: CreateWebhookDeviceEventByProduct
      description: Sends an event to be processed by the specified webhook, addressed by productUID, associated with the given device (provisioning it if necessary). The entire request body becomes the event body. The webhook's configured JSONata transform, if any, is applied before routing.
      parameters:
      - $ref: '#/components/parameters/productUIDParam'
      - $ref: '#/components/parameters/webhookUIDParam'
      - $ref: '#/components/parameters/deviceUIDParam'
      requestBody:
        description: The event body (arbitrary JSON)
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Event created successfully
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - personalAccessToken: []
      tags:
      - Webhook
      x-custom-attributes:
        permission: create
        resource: blues:resources:app:APPSERIAL:notes
      summary: Create webhook device event by product
      x-summary-source: derived
  /v1/products/{productUID}/webhooks/{webhookUID}/event:
    post:
      operationId: CreateWebhookEventByProduct
      description: Sends an event to be processed by the specified webhook, addressed by productUID. The entire request body becomes the event body. The webhook's configured JSONata transform, if any, is applied before routing. The event is not associated with a specific device.
      parameters:
      - $ref: '#/components/parameters/productUIDParam'
      - $ref: '#/components/parameters/webhookUIDParam'
      requestBody:
        description: The event body (arbitrary JSON)
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Event created successfully
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - personalAccessToken: []
      tags:
      - Webhook
      x-custom-attributes:
        permission: create
        resource: blues:resources:app:APPSERIAL:notes
      summary: Create webhook event by product
      x-summary-source: derived
  /v1/products/{productUID}/webhooks/{webhookUID}/settings:
    get:
      operationId: GetWebhookSettingsByProduct
      description: Retrieves the configuration settings for the specified webhook, addressed by productUID.
      parameters:
      - $ref: '#/components/parameters/productUIDParam'
      - $ref: '#/components/parameters/webhookUIDParam'
      responses:
        '200':
          description: Webhook settings retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSettings'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - personalAccessToken: []
      tags:
      - Webhook
      x-custom-attributes:
        permission: update
        resource: blues:resources:app:APPSERIAL:settings
      summary: Get webhook settings by product
      x-summary-source: derived
    put:
      operationId: UpdateWebhookSettingsByProduct
      description: Updates the configuration settings for the specified webhook, addressed by productUID. Update body will completely replace the existing settings.
      parameters:
      - $ref: '#/components/parameters/productUIDParam'
      - $ref: '#/components/parameters/webhookUIDParam'
      requestBody:
        required: true
        content:
          application/json:
            example:
              disabled: false
              transform: '{"device":body.end_device_ids.dev_eui,"sn":body.end_device_ids.device_id,"body":body.uplink_message.decoded_payload,"details":body}'
            schema:
              $ref: '#/components/schemas/WebhookSettings'
      responses:
        '200':
          description: Webhook settings updated successfully
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - personalAccessToken: []
      tags:
      - Webhook
      x-custom-attributes:
        permission: update
        resource: blues:resources:app:APPSERIAL:settings
      summary: Update webhook settings by product
      x-summary-source: derived
  /v1/projects/{projectOrProductUID}/webhooks:
    get:
      operationId: GetWebhooks
      description: Retrieves all webhooks for the specified project
      parameters:
      - $ref: '#/components/parameters/projectOrProductUIDParam'
      responses:
        '200':
          description: Webhooks retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhooks:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookSettings'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - personalAccessToken: []
      tags:
      - Webhook
      x-custom-attributes:
        permission: update
        resource: blues:resources:app:APPSERIAL:settings
      summary: Get webhooks
      x-summary-source: derived
  /v1/projects/{projectOrProductUID}/webhooks/{webhookUID}:
    delete:
      operationId: DeleteWebhook
      description: Deletes the specified webhook
      parameters:
      - $ref: '#/components/parameters/projectOrProductUIDParam'
      - $ref: '#/components/parameters/webhookUIDParam'
      responses:
        '200':
          description: Webhook deleted successfully
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - personalAccessToken: []
      tags:
      - Webhook
      x-custom-attributes:
        permission: update
        resource: blues:resources:app:APPSERIAL:settings
      summary: Delete webhook
      x-summary-source: derived
    get:
      operationId: GetWebhook
      description: Retrieves the configuration settings for the specified webhook
      parameters:
      - $ref: '#/components/parameters/projectOrProductUIDParam'
      - $ref: '#/components/parameters/webhookUIDParam'
      responses:
        '200':
          description: Webhook settings retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSettings'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - personalAccessToken: []
      tags:
      - Webhook
      x-custom-attributes:
        permission: update
        resource: blues:resources:app:APPSERIAL:settings
      summary: Get webhook
      x-summary-source: derived
    post:
      operationId: CreateWebhook
      description: Creates a webhook for the specified product with the given name. The name | must be unique within the project.
      parameters:
      - $ref: '#/components/parameters/projectOrProductUIDParam'
      - $ref: '#/components/parameters/webhookUIDParam'
      requestBody:
        required: true
        content:
          application/json:
            example:
              settings:
                disabled: false
                id: Abc_123-2646f411-dc56-44a0-9743-4130f47a74h8
                transform: '{"device":body.end_device_ids.dev_eui,"sn":body.end_device_ids.device_id,"body":body.uplink_message.decoded_payload,"details":body}'
            schema:
              $ref: '#/components/schemas/WebhookSettings'
      responses:
        '200':
          description: Webhook created successfully
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - personalAccessToken: []
      tags:
      - Webhook
      x-custom-attributes:
        permission: update
        resource: blues:resources:app:APPSERIAL:settings
      summary: Create webhook
      x-summary-source: derived
    put:
      operationId: UpdateWebhook
      description: Updates the configuration settings for the specified webhook. | Webhook will be created if it does not exist. Update body will completely replace the existing settings.
      parameters:
      - $ref: '#/components/parameters/projectOrProductUIDParam'
      - $ref: '#/components/parameters/webhookUIDParam'
      requestBody:
        required: true
        content:
          application/json:
            example:
              disabled: false
              transform: '{"device":body.end_device_ids.dev_eui,"sn":body.end_device_ids.device_id,"body":body.uplink_message.decoded_payload,"details":body}'
            schema:
              $ref: '#/components/schemas/WebhookSettings'
      responses:
        '200':
          description: Webhook updated successfully
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - personalAccessToken: []
      tags:
      - Webhook
      x-custom-attributes:
        permission: update
        resource: blues:resources:app:APPSERIAL:settings
      summary: Update webhook
      x-summary-source: derived
components:
  schemas:
    WebhookSettings:
      type: object
      properties:
        disabled:
          description: Flag indicating if the webhook is disabled
          type: boolean
        id:
          description: Webhook ID
          type: string
        transform:
          description: Transformation to be applied to the event
          type: string
    Error:
      type: object
      properties:
        code:
          description: The HTTP error code associated with the error.
          type: integer
          maximum: 599
          minimum: 300
        debug:
          type: string
        details:
          type: object
        err:
          description: Human readable error message.
          type: string
        request:
          type: string
        status:
          description: Machine readable representation of the HTTP error code.
          type: string
      required:
      - err
      - code
      - status
  responses:
    ErrorResponse:
      description: The response body in case of an API error.
      content:
        application/json:
          schema:
            type: ''
            properties: {}
            $ref: '#/components/schemas/Error'
  parameters:
    deviceUIDParam:
      example: dev:000000000000000
      in: path
      name: deviceUID
      required: true
      schema:
        type: string
    webhookUIDParam:
      description: Webhook UID
      in: path
      name: webhookUID
      required: true
      schema:
        type: string
        example: Abc_123-2646f411-dc56-44a0-9743-4130f47a74h8
    projectOrProductUIDParam:
      example: app:2606f411-dea6-44a0-9743-1130f57d77d8
      in: path
      name: projectOrProductUID
      required: true
      schema:
        type: string
    productUIDParam:
      example: com.blues.bridge:sensors
      in: path
      name: productUID
      required: true
      schema:
        type: string
  securitySchemes:
    personalAccessToken:
      description: 'Use a personal access token from notehub.io/api-access

        '
      scheme: bearer
      type: http
externalDocs:
  description: Find out more about Blues
  url: https://blues.io
x-provenance:
  method: harvested
  publisher: Blues
  source: https://dev.blues.io/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)