openapi: 3.0.1
info:
  title: Environmental Sensor Event Subscription
  description: |
    ## NOTE
    See the [Developer Guide](https://developer.zebra.com/content/data-reporting-electronic-temperature-sensors-developer-guide) for information on what is output in the webhook.

    ## Prerequisites

    You will need:


    1. **Your `tenant`** is the same as your tenant account number. Visit the _**[Tenant Service API](https://developer.zebra.com/apis/review-savanna-tenant-service)**_ on the [Zebra Developer Portal](https://developer.zebra.com/) to retrieve your `tenant` if you don't already have it available.<br/> **Examples**:

    - If you _**don't**_ have an organization account with Zebra your `tenant` should look like this `2e18f99ae1644282a7ead607afb7367d`

    - If you _**do**_ have an organizational account with Zebra your `tenant` should look similar to one of these two formats:

      + `75423`

      + `zebra`.

    2. **A valid `Bearer token`** ***or*** a valid `API Key`.
    You can generate a `Bearer token` by sending your `client_id` and `client_secret` in a `GET` request to Zebra as in this example.
      ```json

        curl --location 'https://api.zebra.com/v2/oauth/token/access' \--header 'client_id: {{your clientId}}' \--header 'client_secret: {{your client secret}}'
            
      ```

  contact: {}
  version: "1.2.2"
servers:
  - url: "https://api.zebra.com/v2/devices/environmental-sensors/event"
    description: Production
paths:
  /subscription:
    post:
      tags:
        - Create Event Subscriptions
      operationId: Create_Subscription
      summary: Creates and starts a webhook subscription
      description: Creates and starts a webhook subscription
      parameters:
        - schema:
            type: string
          name: tenant
          in: header
          required: true
          description: |
            Your `tenant`. See the _[Tenant Service API](https://developer.zebra.com/apis/review-savanna-tenant-service)_ to get your `tenant`.<br/><br/>**Examples**:

            - If you _**don't**_ have an organization account with Zebra your `tenant` should look like this `2e18f99ae1644282a7ead607afb7367d`

            - If you _**do**_ have an organizational account with Zebra your `tenant` should look like one of these two:<br/>

              - `75423`

              - `zebra`
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/create"
            examples:
              basic:
                summary: Basic
                description: |
                  ### taskIds

                  You can specify tasks by their ID to associate them to your webhook subscription. You can associate a task with multiple webhook subscriptions and multiple tasks per subscription. If no task ID is provided, it is assumed **ALL** tasks will go through this webhook. 

                  ### epcis

                  You can set `epcis` to `true` which will return your data in _Electronic Product Code Information Services (EPCIS)_ format or, `false` which will return data in _Universal Data model (UDM)_ format. Default is false.

                  ### name

                  While not a required parameter we highly recommended that you name your webhook subscription with short meaningful names.

                  ### webhookUrl

                  This is the _only_ **required** body parameter. This is destination where you want Zebra to sends webhooks (event messages) for the subscription.

                value:
                  {
                    webhookUrl: "https://hooks.myorganization.com/services/hooks/myendpoint",
                  }
              advanced:
                summary: Advanced
                description: |
                  ### taskIds

                  You can specify tasks by their ID to associate them to your webhook subscription. You can associate a task with multiple webhook subscriptions and multiple tasks per subscription. If no task ID is provided, it is assumed **ALL** tasks will go through this webhook.

                  ### epcis

                  You can set `epcis` to `true` which will return your data in _Electronic Product Code Information Services (EPCIS)_ format or, `false` which will return data in _Universal Data model (UDM)_ format. Default is false.

                  ### name

                  While not a required parameter we highly recommended that you name your webhook subscription with short meaningful names.

                  ### webhookUrl

                  This is the _only_ **required** body parameter. This is destination where you want Zebra to sends webhooks (event messages) for the subscription.

                value:
                  {
                    headers: { "apikey": "abc12345", "tenant": "12345abc" },
                    taskIds:
                      [
                        "449d226f3a1a4ad48e5c552831aa9334",
                        "629427d184744093a5dd3cd6b19c96b1",
                      ],
                    epcis: true,
                    name: "The name of my new webhook subscription",
                    webhookUrl: "https://hooks.myorganization.com/services/hooks/myendpoint",
                    webhookVerb: "POST",
                  }
        description: "Ensure you **check both** the _Basic_ and _Advanced_ request body examples along with their respective descriptions for further explanation."
      responses:
        "200":
          $ref: "#/components/responses/valid"
        "400":
          $ref: "#/components/responses/bad-request"
        "401":
          $ref: "#/components/responses/unauthorized"
        "403":
          $ref: "#/components/responses/forbidden"

    get:
      tags:
        - Manage Event Subscriptions
      operationId: Retrieve_Subscriptions
      summary: Retrieves all subscriptions
      description: Retrieves all environmental sensor webhook subscriptions

      parameters:
        - schema:
            type: string
          name: tenant
          in: header
          required: true
          description: |
            Your `tenant`. See the _[Tenant Service API](https://developer.zebra.com/apis/review-savanna-tenant-service)_ to get your `tenant`.<br/><br/>**Examples**:

            - If you _**don't**_ have an organization account with Zebra your `tenant` should look like this `2e18f99ae1644282a7ead607afb7367d`

            - If you _**do**_ have an organizational account with Zebra your `tenant` should look like one of these two:<br/>

              - `75423`

              - `zebra`
      responses:
        "200":
          $ref: "#/components/responses/all-subscriptions"
        "400":
          $ref: "#/components/responses/bad-request"
        "401":
          $ref: "#/components/responses/unauthorized"
        "403":
          $ref: "#/components/responses/forbidden"

  /subscription/{subscriptionId}/stop:
    parameters:
      - schema:
          type: string
        name: subscriptionId
        in: path
        required: true
        description: |
          Supply the `subscriptionId` of the webhook subscription you want to stop. **Example:** `B5JD07WPJ3BDVXRR`<br/><br/>You can retrieve all your `subscriptionId`(s) using `GET` `/subscription` above.
    post:
      tags:
        - Manage Event Subscriptions
      operationId: Stops_Subscription_by_ID
      summary: Stops a subscription
      description: Stops sending notifications for an environmental sensor webhook subscription
      parameters:
        - schema:
            type: string
          name: tenant
          in: header
          required: true
          description: |
            Your `tenant`. See the _[Tenant Service API](https://developer.zebra.com/apis/review-savanna-tenant-service)_ to get your `tenant`.<br/><br/>**Examples**:

            - If you _**don't**_ have an organization account with Zebra your `tenant` should look like this `2e18f99ae1644282a7ead607afb7367d`

            - If you _**do**_ have an organizational account with Zebra your `tenant` should look like one of these two:<br/>

              - `75423`

              - `zebra`
      responses:
        "200":
          description: OK
          $ref: "#/components/responses/stop-start"
        "400":
          $ref: "#/components/responses/bad-request"
        "401":
          description: Unauthorized
          $ref: "#/components/responses/unauthorized"
        "403":
          description: Forbidden
          $ref: "#/components/responses/forbidden"
        "409":
          description: Conflict
          $ref: "#/components/responses/conflict"
  /subscription/{subscriptionId}/start:
    parameters:
      - schema:
          type: string
        name: subscriptionId
        in: path
        required: true
        description: |
          Supply the `subscriptionId` of the webhook subscription you want to start. **Example:** `B5JD07WPJ3BDVXRR`<br/><br/>You can retrieve all your `subscriptionId`(s) using `GET` `/subscription` above.
    post:
      tags:
        - Manage Event Subscriptions
      operationId: Starts_Subscription_by_ID
      summary: Starts a subscription
      description: Starts sending notifications for an environmental sensor webhook subscription
      parameters:
        - schema:
            type: string
          name: tenant
          in: header
          required: true
          description: |
            Your `tenant`. See the _[Tenant Service API](https://developer.zebra.com/apis/review-savanna-tenant-service)_ to get your `tenant`.<br/><br/>**Examples**:

            - If you _**don't**_ have an organization account with Zebra your `tenant` should look like this `2e18f99ae1644282a7ead607afb7367d`

            - If you _**do**_ have an organizational account with Zebra your `tenant` should look like one of these two:<br/>

              - `75423`

              - `zebra`
      responses:
        "200":
          description: OK
          $ref: "#/components/responses/stop-start"
        "400":
          $ref: "#/components/responses/bad-request"
        "401":
          description: Unauthorized
          $ref: "#/components/responses/unauthorized"
        "403":
          description: Forbidden
          $ref: "#/components/responses/forbidden"
        "409":
          description: Conflict
          $ref: "#/components/responses/conflict"
components:
  schemas:
    all-subscriptions:
      title: allSubscriptions
      description: ""
      type: object
      properties:
        id:
          type: string
          description: This is the `id` of your webhook subscription
          example: B5JD07WPJ3BDVXRR
        deviceIdentifiers:
          type: array
          description: |
            List of `taskIds` to associated with your webhook subscription.
          items:
            type: string
          example:
            - "449d226f3a1a4ad48e5c552831aa9334"
            - "629427d184744093a5dd3cd6b19c96b1"
        deviceScope:
          type: string
          minLength: 8
          maxItems: 8
          description: The value for the key `deviceScope` is set to `SCOVILLE` automatically upon creation of the webhook subscription for this API. This is required.
        name:
          type: string
          description: The name of your subscription
          example: "My subscription name"
        changeFields:
          type: array
          description: |
            Value set when processing the creation of a webhook subscription.  Refers to how the webhook is created.
          items:
            type: string
          example:
            - "webhookTrigger"
        epcis:
          type: boolean
          description: |
            Set to `true` will return `rawData` `epcisEventData`, `false` will return `rawData` `webhookTrigger`
          items:
            type: boolean
          example:
            - "true"
            - "false"
        webhookUrl:
          type: string
          description: The URL of your server endpoint.
          example: "https://hooks.myorganization.com/services/hooks/myendpoint"
        webhookVerb:
          type: string
          description: |
            HTTP Method to use for the webhook subscription
          example: POST
        rawData:
          type: string
          description: |
            Static field that will return `epcisEventData` for EPCIS responses and `webhookTrigger` for non-EPCIS responses
          example: "epcisEventData"
    bad-request:
      title: badRequest
      description: The server cannot process your request
      type: object
      properties:
        code:
          type: string
          example: 400
        message:
          type: string
          example: Bad Request
        info:
          type: string
          example: The server cannot process your request
      example:
        code: 400
        message: Bad Request
        info: The server cannot process your request
    conflict:
      title: conflict
      description: Request is incompatible with a previous request
      type: object
      properties:
        code:
          type: string
          example: 409
        message:
          type: string
          example: Conflict
        info:
          type: string
          example: Your request is incompatible with a previous request.
      example:
        code: 409
        message: Conflict
        info: Your request is incompatible with a previous request.
    create:
      title: create
      description: ""
      type: object
      required:
        - webhookUrl
      properties:
        taskIds:
          type: array
          description: |
            List of `taskIds` to associated with your webhook subscription. If nothing is entered, all tasks will send their events to this webhook.
          items:
            type: string
          example:
            - "449d226f3a1a4ad48e5c552831aa9334"
            - "629427d184744093a5dd3cd6b19c96b1"
        epcis:
          type: boolean
          description: |
            Set to `true` will return data in _Electronic Product Code Information Services (EPCIS)_ format, `false` will return data in _Universal Data model (UDM)_ format.
          example: true
          default: false
        headers:
          type: string
          description: |
            Allows you to add authentication or other headers to the webhooks to secure your endpoint.
          example: { "apikey": "abc12345", "tenant": "12345abc" }
        name:
          type: string
          minLength: 2
          description: |
            The name you provide to describe a webhook subscription
          example: My webhook subscription
        webhookUrl:
          type: string
          minLength: 1
          description: |
            The URI of your server endpoint. Destination to which Zebra will send event messages for the subscription.
          example: "https://hooks.myorganization.com/services/hooks/myendpoint"
        webhookVerb:
          type: string
          minLength: 3
          maxLength: 7
          enum: [POST, PUT]
          default: "POST"
          description: |
            HTTP Method to use for the webhook subscription.
          example: "POST"
    created:
      title: created
      description: ""
      type: object
      properties:
        subscription:
          type: string
          example:
            id: B5JD07WPJ3BDVXR
    forbidden:
      title: forbidden
      description: You do not have access to this tenant
      type: object
      properties:
        code:
          type: string
          example: 403
        message:
          type: string
          example: Forbidden
        info:
          type: string
          example: You do not have access to this tenant
      example:
        code: 403
        message: Forbidden
        info: You do not have access to this tenant
    stop-start:
      title: stopStartSuccess
      description: _**empty**_ `200 OK` response upon successful stop or start of a webhook subscription
      type: object
      properties:
        200:
          type: string
          example: {}
      example:
        200: {}
    unauthorized:
      title: unauthorized
      description: Invalid Access Token
      type: object
      properties:
        code:
          type: string
          example: 401
        message:
          type: string
          example: Unauthorized
        info:
          type: string
          example: Invalid Access Token
      example:
        code: 401
        message: Unauthorized
        info: Invalid Access Token
    subscription:
      title: subscription
      description: ""
      type: object
      properties:
        name:
          type: string
          description: The name of your subscription
          example: "My subscription name"
        epcis:
          type: boolean
          description: |
            Set to `true` will return `rawData` `epcisEventData`, `false` will return `rawData` `webhookTrigger`
          items:
            type: boolean
          example:
            - "true"
            - "false"
        changeFields:
          type: array
          description: This is a fixed value for this API. Refers to how the webhooks are created.
          items:
            type: string
          example:
            - webhookTrigger
        taskIds:
          type: array
          description: "List of `taskIds` to associated with your webhook subscription. NOTE: Leaving this blank will return all tasks."
          items:
            type: string
          example:
            - "449d226f3a1a4ad48e5c552831aa9334"
            - "629427d184744093a5dd3cd6b19c96b1"
        webhookVerb:
          type: string
          description: |
            HTTP Method to use for the webhook subscription
          example: POST
        webhookUrl:
          type: string
          description: The URL of your server endpoint.
          example: "https://hooks.myorganization.com/services/hooks/myendpoint"
        id:
          type: string
          description: This is the `id` of your webhook subscription
          example: B5JD07WPJ3BDVXRR
        deviceScope:
          type: string
          minLength: 8
          maxItems: 8
          description: The value for the key `deviceScope` must be set to `SCOVILLE` for this API. If you do not pass this key-value pair in your request it will be set in processing your request body.
      required:
        - webhookUrl

  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      description: |
        **A valid `Bearer token`**. You can generate a `Bearer token` by sending your `client_id` and `client_secret` in a `GET` request to Zebra.
    ApiKeyAuth:
      type: apiKey
      in: header
      name: apikey
      description: See the [Apps](https://developer.zebra.com/user/apps) page
  responses:
    all-subscriptions:
      description: Example response
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/all-subscriptions"
          examples:
            example:
              value:
                subscriptions:
                  [
                    {
                      "id": "JSNR794PFLK6AXRP",
                      "deviceScope": "SCOVILLE",
                      "name": "My webhook subscription",
                      "changeFields": ["webhookTrigger"],
                      "deviceIdentifiers":
                        ["085d4f08-7f39-43cd-8c01-a9ce017a58c0"],
                      "epcis": true,
                      "webhookUrl": "https://webhook.site/6c41a68d-9d5c-47a1-9920-87d420e6d0ad",
                      "webhookVerb": "POST",
                      "rawData": ["epcisEventData"],
                    },
                    {
                      "id": "L9YAB9SW5ZE857T6",
                      "deviceScope": "SCOVILLE",
                      "name": "My alerts subscription",
                      "changeFields": ["webhookTrigger"],
                      "deviceIdentifiers":
                        ["4515ab2e-cea4-43b8-8144-84f5d136ebc6"],
                      "epcis": true,
                      "webhookUrl": "https://webhook.site/4cd8c3d0-657f-4c7a-a967-fc18c9e3c058",
                      "webhookVerb": "POST",
                    },
                    {
                      "id": "XYXNVRDTFGIUG1ZA",
                      "deviceScope": "SCOVILLE",
                      "name": "Test alerts",
                      "changeFields": ["webhookTrigger"],
                      "epcis": true,
                      "webhookUrl": "https://webhook.site/f550af3e-712d-4f43-ada6-6a1a34775cfd",
                      "webhookVerb": "POST",
                      "rawData": ["epcisEventData"],
                    },
                  ]
    bad-request:
      description: You are likely to receive a `400 Bad Request` response when you haven't supplied all of the required parameters for your request or the syntax of your request or one of your parameter is incorrect.<br/><br/>Please check all the parameters you provided along with their syntax and try again.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/bad-request"
          examples:
            example:
              value:
                errorResponse:
                  code: "400"
                  message: "Bad Request"
                  info: The server cannot process your request
    conflict:
      description: You will receive a `409 Conflict` response when you try to start a subscription that is already running or stop a subscription that has already been stopped.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/conflict"
          examples:
            example:
              value:
                errorResponse:
                  code: "409"
                  message: "Conflict"
                  info: "Your request is incompatible with a previous request."
    forbidden:
      description: You will receive a `403 Forbidden` response when you do not have access to the tenant which you are attempting to use.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/forbidden"
          examples:
            example:
              value:
                errorResponse:
                  code: "403"
                  message: "Forbidden"
                  info: "You do not have access to this tenant"
    stop-start:
      description: You will receive an _**empty**_ `200 OK` response upon successfully stopping or starting your webhook subscription.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/stop-start"
          example: {}
    unauthorized:
      description: You will receive a `401 Unauthorized` response when the `Bearer token` you supplied is no longer valid.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/unauthorized"
          examples:
            example:
              value:
                errorResponse:
                  code: "401"
                  message: "Unauthorized"
                  info: "Invalid Access Token"
    valid:
      description: You will receive a `200 OK` response upon successful creation and initiation of your webhook subscription which will provide your subscription ID.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/created"
          example:
            subscription: { id: B5JD07WPJ3BDVXRR }
security:
  - Authorization: []
  - ApiKeyAuth: []

tags:
  - name: Event Subscription
