openapi: 3.0.0
info:
  description: Polar AccessLink API documentation
  version: v3
  title: Polar AccessLink Cardio load Webhooks API
  contact:
    name: Support
    url: https://www.polar.com/accesslink
    email: b2bhelpdesk@polar.com
  license:
    name: Polar Electro AccessLink Limited License Agreement
    url: https://www.polar.com/en/legal/polar-api-agreement
servers:
- url: https://www.polaraccesslink.com/
tags:
- name: Webhooks
  description: Webhook resources provides endpoints for creating, modifying and deleting webhooks.
paths:
  /v3/webhooks:
    post:
      tags:
      - Webhooks
      summary: Create webhook
      description: 'Create new webhook.


        When creating webhook the AccessLink sends a ping message to the url in request body. The ping message must be answered with 200 OK or otherwise the webhook is not created.


        Created webhook is by default in activated state and will send push notifications about subscribed events. Webhook will be automatically deactivated if push notifications have not been successful for a period of seven (7) days.

        **Note!** Save the *signature_secret_key* from response since this is the only chance to get it.'
      operationId: createWebhook
      responses:
        '201':
          description: Created webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/createdWebhook'
        '400':
          description: Webhook cannot be created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '409':
          description: Webhook already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - Basic: []
      requestBody:
        description: Webhook to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhookRequest'
        required: true
    get:
      tags:
      - Webhooks
      summary: Get webhook
      description: Returns created webhook if exists.
      operationId: getWebhook
      responses:
        '200':
          description: Existing webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhookInfo'
      security:
      - Basic: []
  /v3/webhooks/activate:
    post:
      tags:
      - Webhooks
      summary: Activate webhook
      description: Activate deactivated webhook. Activation is successful if the configured webhook url returns HTTP status 200 (OK) for the issued ping request.
      responses:
        '200':
          description: Webhook has been successfully activated.
        '204':
          description: Webhook does not exist and it cannot be activated.
      security:
      - Basic: []
  /v3/webhooks/deactivate:
    post:
      tags:
      - Webhooks
      summary: Deactivate webhook
      description: Deactivate activated webhook. Deactivated webhook does not push notifications about subscribed events.
      responses:
        '200':
          description: Webhook has been successfully deactivated.
        '204':
          description: Webhook does not exist and it cannot be deactivated.
      security:
      - Basic: []
  /v3/webhooks/{webhook-id}:
    patch:
      tags:
      - Webhooks
      summary: Update webhook
      description: 'Edit webhook event types and/or url.


        When updating webhook url the AccessLink sends a ping message to the new address. The ping message must be answered with 200 OK or otherwise the webhook is not updated.'
      operationId: updateWebhook
      parameters:
      - name: webhook-id
        in: path
        description: Webhook id to update
        required: true
        schema:
          type: string
      requestBody:
        description: New value(s) for events and/or url.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhookPatch'
        required: true
      responses:
        '200':
          description: Webhook updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhookInfo'
        '400':
          description: Webhook cannot be updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Webhook not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - Basic: []
    delete:
      tags:
      - Webhooks
      summary: Delete webhook
      description: Delete webhook by id.
      operationId: deleteWebhook
      parameters:
      - name: webhook-id
        in: path
        description: Webhook id to delete
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Webhook deleted successfully.
        '404':
          description: Webhook not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - Basic: []
components:
  schemas:
    error:
      type: object
      description: Error model which contains useful info about the error occurred.
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the error.
        status:
          type: integer
          description: Http status code
        errorType:
          type: string
          description: Error type.
        message:
          type: string
          description: Human readable error message.
        corrId:
          type: string
          description: Correlation id of the response for problem solving and debugging use.
    webhookPatch:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/webhookType'
          description: Type of events to subscribe.
          example:
          - EXERCISE
        url:
          type: string
          format: uri
          example: https://myapp.example.com/acl_webhook
          description: Url where the webhook notification is sent.
    createdWebhook:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              example: abdf33
              description: Id of the new webhook.
            events:
              type: array
              items:
                $ref: '#/components/schemas/webhookType'
              description: Subscribed event types.
              example:
              - EXERCISE
            url:
              type: string
              format: uri
              example: https://myapp.example.com/acl_webhook
              description: Url where the webhook notification is sent.
            signature_secret_key:
              type: string
              example: abe1f3ae-fd33-11e8-8eb2-f2801f1b9fd1
              description: Signing key for verifying that sender is actually Polar.
    webhookInfo:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                example: abdf33
                description: Id of the webhook.
              events:
                type: array
                items:
                  $ref: '#/components/schemas/webhookType'
                description: Subscribed event types.
                example:
                - EXERCISE
              url:
                type: string
                format: uri
                example: https://myapp.example.com/acl_webhook
                description: Url where the webhook notification is sent.
              active:
                type: boolean
                example: true
                description: Is the webhook active.
    webhookRequest:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/webhookType'
          description: Type of events to subscribe.
          example:
          - EXERCISE
        url:
          type: string
          format: uri
          example: https://myapp.example.com/acl_webhook
          description: Url where the webhook notification is sent.
      required:
      - events
      - url
    webhookType:
      type: string
      enum:
      - EXERCISE
      - SLEEP
      - CONTINUOUS_HEART_RATE
      - SLEEP_WISE_CIRCADIAN_BEDTIME
      - SLEEP_WISE_ALERTNESS
      - ACTIVITY_SUMMARY
      - PHYSICAL_INFORMATION
      description: Event type to subscribe. Currently EXERCISE, SLEEP, CONTINUOUS_HEART_RATE, SLEEP_WISE_CIRCADIAN_BEDTIME, SLEEP_WISE_ALERTNESS, ACTIVITY_SUMMARY and PHYSICAL_INFORMATION are supported.
  securitySchemes:
    Basic:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://flow.polar.com/oauth2/authorization
          tokenUrl: https://polarremote.com/v2/oauth2/token
          scopes:
            accesslink.read_all: Allows read access to user's data