webhooks.yaml

openapi: 3.0.3
info:
  description: |
    This API describes the event webhook calling convention.
    In order to receive webhook events from the gridX API, third parties must implement endpoints according to this specification. In the following, the external partner API is referred to as  "external API", while the gridX API is called "gridX".
  title: gridX Webhook Event Receiver API
  version: 1.0.0
  x-audience: company-internal
  x-api-id: 7b2283ae-4623-42c2-af84-ef6ce4d72993
servers:
- url: https://your-webhook-receiver-url-goes-here/gridx
- url: http://localhost:8080/gridx
paths:
  /events/appliance/create:
    post:
      description: "Called by the gridX API when an appliance is created."
      parameters:
      - description: |
          The value of this header can be used to authenticate the event payload and is in the format `<method>=<signature>`.
          - `method` must be "sha512" in any case.
          - `signature` is computed using the HMAC algorithm (as described in [RFC2104](https://datatracker.ietf.org/doc/html/rfc2104)) with SHA512 as hash function, with the request body as data and a pre-defined secret as key (that is only known between the external API and gridX).
          This is the same method as described in the W3C WebSub standard X-Hub-Signature, see: https://www.w3.org/TR/websub/#authenticated-content-distribution
        example: sha512=<signature>
        explode: false
        in: header
        name: X-Signature
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplianceCreateEvent'
        description: "The event's payload, partly depending on the event's type (see\
          \ parameter eventType)."
        required: true
      responses:
        "200":
          description: |
            Successfully received event (no issue with payload or validation).
        "403":
          description: |
            Indicate that signature validation was not successful.
        "404":
          description: |
            Not Found - indicate that the external API is not available.
        "500":
          description: |
            Indicate that there is a temporary fault on the external API. gridX will do its best to retry delivery in this case.
        "503":
          description: |
            Indicate that the service is temporarily unavailable. gridX will do its best to retry delivery in this case.
      summary: Webhook Receiver
      tags:
      - Webhook Receiver
  /events/appliance/offline:
    post:
      description: "Called by the gridX API when when an appliance goes offline."
      parameters:
      - description: |
          The value of this header can be used to authenticate the event payload and is in the format `<method>=<signature>`.
          - `method` must be "sha512" in any case.
          - `signature` is computed using the HMAC algorithm (as described in [RFC2104](https://datatracker.ietf.org/doc/html/rfc2104)) with SHA512 as hash function, with the request body as data and a pre-defined secret as key (that is only known between the external API and gridX).
          This is the same method as described in the W3C WebSub standard X-Hub-Signature, see: https://www.w3.org/TR/websub/#authenticated-content-distribution
        example: sha512=<signature>
        explode: false
        in: header
        name: X-Signature
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplianceOfflineEvent'
        required: true
      responses:
        "200":
          description: |
            Successfully received event (no issue with payload or validation).
        "403":
          description: |
            Indicate that signature validation was not successful.
        "404":
          description: |
            Not Found - indicate that the external API is not available.
        "500":
          description: |
            Indicate that there is a temporary fault on the external API. gridX will do its best to retry delivery in this case.
        "503":
          description: |
            Indicate that the service is temporarily unavailable. gridX will do its best to retry delivery in this case.
      summary: Webhook Receiver
      tags:
      - Webhook Receiver
  /events/appliance/online:
    post:
      description: "Called by the gridX API when an appliance comes online."
      parameters:
      - description: |
          The value of this header can be used to authenticate the event payload and is in the format `<method>=<signature>`.
          - `method` must be "sha512" in any case.
          - `signature` is computed using the HMAC algorithm (as described in [RFC2104](https://datatracker.ietf.org/doc/html/rfc2104)) with SHA512 as hash function, with the request body as data and a pre-defined secret as key (that is only known between the external API and gridX).
          This is the same method as described in the W3C WebSub standard X-Hub-Signature, see: https://www.w3.org/TR/websub/#authenticated-content-distribution
        example: sha512=<signature>
        explode: false
        in: header
        name: X-Signature
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplianceOnlineEvent'
        required: true
      responses:
        "200":
          description: |
            Successfully received event (no issue with payload or validation).
        "403":
          description: |
            Indicate that signature validation was not successful.
        "404":
          description: |
            Not Found - indicate that the external API is not available.
        "500":
          description: |
            Indicate that there is a temporary fault on the external API. gridX will do its best to retry delivery in this case.
        "503":
          description: |
            Indicate that the service is temporarily unavailable. gridX will do its best to retry delivery in this case.
      summary: Webhook Receiver
      tags:
      - Webhook Receiver
  /events/inverter/status:
    post:
      description: "Called by the gridX API when an inverter's status changes."
      parameters:
      - description: |
          The value of this header can be used to authenticate the event payload and is in the format `<method>=<signature>`.
          - `method` must be "sha512" in any case.
          - `signature` is computed using the HMAC algorithm (as described in [RFC2104](https://datatracker.ietf.org/doc/html/rfc2104)) with SHA512 as hash function, with the request body as data and a pre-defined secret as key (that is only known between the external API and gridX).
          This is the same method as described in the W3C WebSub standard X-Hub-Signature, see: https://www.w3.org/TR/websub/#authenticated-content-distribution
        example: sha512=<signature>
        explode: false
        in: header
        name: X-Signature
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InverterStatusEvent'
        required: true
      responses:
        "200":
          description: |
            Successfully received event (no issue with payload or validation).
        "403":
          description: |
            Indicate that signature validation was not successful.
        "404":
          description: |
            Not Found - indicate that the external API is not available.
        "500":
          description: |
            Indicate that there is a temporary fault on the external API. gridX will do its best to retry delivery in this case.
        "503":
          description: |
            Indicate that the service is temporarily unavailable. gridX will do its best to retry delivery in this case.
      summary: Webhook Receiver
      tags:
      - Webhook Receiver
  /events/gateway/create:
    post:
      description: "Called by the gridX API when a gateway is created."
      parameters:
      - description: |
          The value of this header can be used to authenticate the event payload and is in the format `<method>=<signature>`.
          - `method` must be "sha512" in any case.
          - `signature` is computed using the HMAC algorithm (as described in [RFC2104](https://datatracker.ietf.org/doc/html/rfc2104)) with SHA512 as hash function, with the request body as data and a pre-defined secret as key (that is only known between the external API and gridX).
          This is the same method as described in the W3C WebSub standard X-Hub-Signature, see: https://www.w3.org/TR/websub/#authenticated-content-distribution
        example: sha512=<signature>
        explode: false
        in: header
        name: X-Signature
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GatewayCreateEvent'
        required: true
      responses:
        "200":
          description: |
            Successfully received event (no issue with payload or validation).
        "403":
          description: |
            Indicate that signature validation was not successful.
        "404":
          description: |
            Not Found - indicate that the external API is not available.
        "500":
          description: |
            Indicate that there is a temporary fault on the external API. gridX will do its best to retry delivery in this case.
        "503":
          description: |
            Indicate that the service is temporarily unavailable. gridX will do its best to retry delivery in this case.
      summary: Webhook Receiver
      tags:
      - Webhook Receiver
  /events/gateway/offline:
    post:
      description: "Called by the gridX API when a gateway goes offline."
      parameters:
      - description: |
          The value of this header can be used to authenticate the event payload and is in the format `<method>=<signature>`.
          - `method` must be "sha512" in any case.
          - `signature` is computed using the HMAC algorithm (as described in [RFC2104](https://datatracker.ietf.org/doc/html/rfc2104)) with SHA512 as hash function, with the request body as data and a pre-defined secret as key (that is only known between the external API and gridX).
          This is the same method as described in the W3C WebSub standard X-Hub-Signature, see: https://www.w3.org/TR/websub/#authenticated-content-distribution
        example: sha512=<signature>
        explode: false
        in: header
        name: X-Signature
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GatewayOfflineEvent'
        required: true
      responses:
        "200":
          description: |
            Successfully received event (no issue with payload or validation).
        "403":
          description: |
            Indicate that signature validation was not successful.
        "404":
          description: |
            Not Found - indicate that the external API is not available.
        "500":
          description: |
            Indicate that there is a temporary fault on the external API. gridX will do its best to retry delivery in this case.
        "503":
          description: |
            Indicate that the service is temporarily unavailable. gridX will do its best to retry delivery in this case.
      summary: Webhook Receiver
      tags:
      - Webhook Receiver
  /events/gateway/online:
    post:
      description: "Called by the gridX API when a gateway comes online."
      parameters:
      - description: |
          The value of this header can be used to authenticate the event payload and is in the format `<method>=<signature>`.
          - `method` must be "sha512" in any case.
          - `signature` is computed using the HMAC algorithm (as described in [RFC2104](https://datatracker.ietf.org/doc/html/rfc2104)) with SHA512 as hash function, with the request body as data and a pre-defined secret as key (that is only known between the external API and gridX).
          This is the same method as described in the W3C WebSub standard X-Hub-Signature, see: https://www.w3.org/TR/websub/#authenticated-content-distribution
        example: sha512=<signature>
        explode: false
        in: header
        name: X-Signature
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GatewayOnlineEvent'
        required: true
      responses:
        "200":
          description: |
            Successfully received event (no issue with payload or validation).
        "403":
          description: |
            Indicate that signature validation was not successful.
        "404":
          description: |
            Not Found - indicate that the external API is not available.
        "500":
          description: |
            Indicate that there is a temporary fault on the external API. gridX will do its best to retry delivery in this case.
        "503":
          description: |
            Indicate that the service is temporarily unavailable. gridX will do its best to retry delivery in this case.
      summary: Webhook Receiver
      tags:
      - Webhook Receiver
  /events/ev/plugged:
    post:
      description: "Called by the gridX API when an EV charging state changes."
      parameters:
      - description: |
          The value of this header can be used to authenticate the event payload and is in the format `<method>=<signature>`.
          - `method` must be "sha512" in any case.
          - `signature` is computed using the HMAC algorithm (as described in [RFC2104](https://datatracker.ietf.org/doc/html/rfc2104)) with SHA512 as hash function, with the request body as data and a pre-defined secret as key (that is only known between the external API and gridX).
          This is the same method as described in the W3C WebSub standard X-Hub-Signature, see: https://www.w3.org/TR/websub/#authenticated-content-distribution
        example: sha512=<signature>
        explode: false
        in: header
        name: X-Signature
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EVPluggedEvent'
        required: true
      responses:
        "200":
          description: |
            Successfully received event (no issue with payload or validation).
        "403":
          description: |
            Indicate that signature validation was not successful.
        "404":
          description: |
            Not Found - indicate that the external API is not available.
        "500":
          description: |
            Indicate that there is a temporary fault on the external API. gridX will do its best to retry delivery in this case.
        "503":
          description: |
            Indicate that the service is temporarily unavailable. gridX will do its best to retry delivery in this case.
      summary: Webhook Receiver
      tags:
      - Webhook Receiver
  /events/comissioning/done:
    post:
      description: "Called by the gridX API when commissioning a gateway was finished."
      parameters:
      - description: |
          The value of this header can be used to authenticate the event payload and is in the format `<method>=<signature>`.
          - `method` must be "sha512" in any case.
          - `signature` is computed using the HMAC algorithm (as described in [RFC2104](https://datatracker.ietf.org/doc/html/rfc2104)) with SHA512 as hash function, with the request body as data and a pre-defined secret as key (that is only known between the external API and gridX).
          This is the same method as described in the W3C WebSub standard X-Hub-Signature, see: https://www.w3.org/TR/websub/#authenticated-content-distribution
        example: sha512=<signature>
        explode: false
        in: header
        name: X-Signature
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ComissioningDoneEvent'
        required: true
      responses:
        "200":
          description: |
            Successfully received event (no issue with payload or validation).
        "403":
          description: |
            Indicate that signature validation was not successful.
        "404":
          description: |
            Not Found - indicate that the external API is not available.
        "500":
          description: |
            Indicate that there is a temporary fault on the external API. gridX will do its best to retry delivery in this case.
        "503":
          description: |
            Indicate that the service is temporarily unavailable. gridX will do its best to retry delivery in this case.
      summary: Webhook Receiver
      tags:
      - Webhook Receiver
components:
  schemas:
    BasicEvent:
      description: |
        Event which follows the [CloudEvents v1.0.1 specification](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md).  An event consists of metadata (such as occurrence time and ID) and the actual `data` payload that depends on the event's `type`. The extension attribute `notification` can be used by consumers to produce a notification.
      properties:
        id:
          format: uuid
          type: string
        time:
          description: Time when the event has occurred in RFC3339 format.
          format: date-time
          type: string
        dataContentType:
          default: application/json
          description: "Content-Type indicating how to parse the `data` attribute.\
            \ Only 'application/json' is supported for now. If omitted, it is guaranteed\
            \ to be `application/json`."
          enum:
          - application/json
          example: application/json
          type: string
        specVersion:
          description: "The CloudEvents specification that is followed, currently\
            \ \"1.0\". Only consists of major and minor version parts, to allow patching\
            \ in a backward-compatible fashion."
          example: "1.0"
          type: string
        source:
          description: "Source of the event, which is usually a resource identifier\
            \ path that can be used to identify the object which triggered the event."
          example: /systems/5eda17ec-4dc9-46d5-b3b8-c396f75a760f
          type: string
        correlationID:
          description: ID to identify the request triggering the event.
          format: uuid
          type: string
      required:
      - id
      - source
      - specVersion
      - time
      title: Event
    ApplianceCreateEvent:
      allOf:
      - $ref: '#/components/schemas/BasicEvent'
      - properties:
          type:
            enum:
            - appliance/create
            type: string
          data:
            $ref: '#/components/schemas/ApplianceEventData'
        required:
        - type
        type: object
      title: Event appliance/create
    ApplianceOfflineEvent:
      allOf:
      - $ref: '#/components/schemas/BasicEvent'
      - properties:
          type:
            enum:
            - appliance/offline
            type: string
          data:
            $ref: '#/components/schemas/ApplianceEventData'
        required:
        - type
        type: object
      title: Event appliance/offline
    ApplianceOnlineEvent:
      allOf:
      - $ref: '#/components/schemas/BasicEvent'
      - properties:
          type:
            enum:
            - appliance/online
            type: string
          data:
            $ref: '#/components/schemas/ApplianceEventData'
        required:
        - type
        type: object
      title: Event appliance/online
    InverterStatusEvent:
      allOf:
      - $ref: '#/components/schemas/BasicEvent'
      - properties:
          type:
            enum:
            - inverter/status
            type: string
          data:
            $ref: '#/components/schemas/InverterEventData'
        required:
        - type
        type: object
      title: Event inverter/status
    GatewayCreateEvent:
      allOf:
      - $ref: '#/components/schemas/BasicEvent'
      - properties:
          type:
            enum:
            - gateway/create
            type: string
          data:
            $ref: '#/components/schemas/GatewayEventData'
        required:
        - type
        type: object
      title: Event gateway/create
    GatewayOfflineEvent:
      allOf:
      - $ref: '#/components/schemas/BasicEvent'
      - properties:
          type:
            enum:
            - gateway/offline
            type: string
          data:
            $ref: '#/components/schemas/GatewayEventData'
        required:
        - type
        type: object
      title: Event gateway/offline
    GatewayOnlineEvent:
      allOf:
      - $ref: '#/components/schemas/BasicEvent'
      - properties:
          type:
            enum:
            - gateway/online
            type: string
          data:
            $ref: '#/components/schemas/GatewayEventData'
        required:
        - type
        type: object
      title: Event gateway/online
    EVPluggedEvent:
      allOf:
      - $ref: '#/components/schemas/BasicEvent'
      - properties:
          type:
            enum:
            - ev/plugged
            type: string
          data:
            $ref: '#/components/schemas/EVEventData'
        required:
        - type
        type: object
      title: Event ev/plugged
    ComissioningDoneEvent:
      allOf:
      - $ref: '#/components/schemas/BasicEvent'
      - properties:
          type:
            enum:
            - commissioning/done
            type: string
          data:
            $ref: '#/components/schemas/CommissioningData'
        required:
        - type
        type: object
      title: Event commissioning/done
    GatewayEventData:
      description: Payload for `gateway/*` events.
      properties:
        gatewayID:
          description: The ID of the gateway this event is triggered for.
          example: 680d63aa-6e1d-4447-af7c-35c5eb6ca810
          format: uuid
          type: string
        gatewayName:
          description: The name of the gateway corresponding to the gatewayID.
          example: My gridBox
          type: string
        gatewaySerialnumber:
          description: The serialnumber of the gateway corresponding to the gatewayID.
          example: D403-007-000-000-001-B-X
          type: string
        systemID:
          description: The ID of the system this event is triggered for.
          example: af87d7b3-316f-4d26-868c-4ae351095bdc
          format: uuid
          type: string
        systemName:
          description: The name of the system corresponding to the systemID.
          example: ExampleSystem
          type: string
        userID:
          description: The ID of the user that owns the system.
          example: a115d9e3-6e78-4ddf-8676-a98c28ad8249
          format: uuid
          type: string
        userName:
          description: Name of the user belonging to the userID.
          example: Max Mustermann
          type: string
        userMail:
          description: E-Mail address of the user belonging to the userID.
          example: max.mustermann@muster.de
          type: string
      required:
      - gatewayID
      - systemID
      type: object
    ApplianceEventData:
      description: Payload for `appliance/*` events.
      properties:
        applianceID:
          description: ID of the appliance that caused this event.
          example: fc0a6ac7-64ce-4276-a7cd-bace946af433
          format: uuid
          type: string
        gatewayID:
          description: The ID of the gateway that connects to the appliance.
          example: 25ccab17-cd40-4db1-a320-a986d1c15fb1
          format: uuid
          type: string
        model:
          description: Model description of the appliance.
          example: Baz
          type: string
        manufacturer:
          description: Manufacturer of the appliance.
          example: Iskraemeco
          type: string
        type:
          description: General type of the appliance.
          enum:
          - UNKNOWN
          - INVERTER
          - METER
          - EVSTATION
          - HEAT_PUMP
          - HEATER
          - CONTAINER
          example: METER
          type: string
        kind:
          description: |
            Kind of the appliance is used to provide further details on the appliance configuration and mode of operation. The kind property is only available for appliances with type INVERTER or METER. For inverters, only UNKNOWN, PV, BATTERY, HYBRID and PV_EXTERNAL are valid values. They describe the  kind of connected appliance(s) and define the role of the inverter in the system. For meters, kind specifies the appliance the meter is attached to. It resembles the location the meter is installed in.
          enum:
          - UNKNOWN
          - PV
          - BATTERY
          - HYBRID
          - PV_EXTERNAL
          - GRID
          - HEAT_PUMP
          - FUEL_CELL
          - HEAT_PUMP_EXTERNAL
          - EVSTATION
          - BTTP
          - HEATING
          - MISC
          - CLUSTER
          - WIND_TURBINE
          example: BATTERY
          type: string
        name:
          description: The name of the appliance as defined by the customer.
          example: ExampleMeter
          type: string
        serialNumber:
          description: Serial number of the appliance as returned by the appliance.
          example: "9312355"
          type: string
        systemID:
          description: The ID of the system that the gateway and appliance run in.
          example: c9db369e-7cf8-4ad1-ade5-46f61a5125c2
          format: uuid
          type: string
        systemName:
          description: Name of the system as defined by the customer.
          example: ExampleSystem
          type: string
      required:
      - applianceID
      - gatewayID
      - systemID
      type: object
    InverterEventData:
      allOf:
      - $ref: '#/components/schemas/ApplianceEventData'
      - properties:
          status:
            description: Current (new) status of the inverter.
            enum:
            - UNKNOWN
            - OK
            - WARNING
            - ERROR
            example: OK
            type: string
          lastStatus:
            description: Last status of the inverter.
            enum:
            - UNKNOWN
            - OK
            - WARNING
            - ERROR
            example: ERROR
            type: string
          errCode:
            description: |
              Current (new) error code as returned by the appliance. The value depends on the appliance manufacturer, model and firmware. Please refer to the manufacturers specification.
            type: string
          lastErrCode:
            description: |
              Last error code as returned by the appliance. The value depends on the appliance manufacturer, model and firmware. Please refer to the manufacturers specification.
            example: F71A
            type: string
        required:
        - lastStatus
        - status
        type: object
      description: |
        Payload for `inverter/*` events. The event describes the change of an inverter from one status to a new one. The old status is referred to as the lastStatus.
    EVEventData:
      allOf:
      - $ref: '#/components/schemas/ApplianceEventData'
      - properties:
          evseID:
            description: Electirc Vehicle Supply Equipment ID
            example: FR*A23*E45B*78C
            type: string
          state:
            description: State of the EV charging station.
            enum:
            - plugged
            example: plugged
            type: string
        required:
        - state
        type: object
      description: |
        Payload for `ev/*` events. The event describes the change of an EV's state at a charging station.
    CommissioningData:
      description: Payload for `commissioning/done` events.
      properties:
        customerID:
          description: The ID of the newly created customer after the commissioning
            process.
          example: 1a81c4f4-5f6c-48e6-be91-2528c1c0bb28
          format: uuid
          type: string
        customerEmail:
          description: The email of the newly created customer after the commissioning
            process.
          example: test@email.com
          format: email
          type: string
        customerAddress:
          description: The address of the newly created customer after the commissioning
            process.
          example: "Straße Str. 1, 20359, Hamburg, Germany"
          format: string
          type: string
        systemName:
          description: The name of the commissioned system.
          example: Test system
          format: string
          type: string
        gatewaySerialnumber:
          description: The serialnumber of the gateway corresponding to the commissioned
            system.
          example: D403-007-000-000-001-B-X
          type: string
      type: object