openapi: 3.0.1
info:
  title: Webhooks API
  description: >-
    The Webhooks API enables you to get HTTP notifications for subscribed
    events.

    See the [Webhooks API guide](/docs/APIs/webhooks-api/api-guide/) for more
    details.
  version: v1
servers:
  - url: https://api.vipps.no/webhooks
    description: Production (Prod)
  - url: https://apitest.vipps.no/webhooks
    description: Test (MT)
paths:
  /v1/webhooks:
    get:
      tags:
        - v1
      summary: Get all registered webhooks
      parameters:
        - name: Ocp-Apim-Subscription-Key
          in: header
          description: The subscription key
          required: true
          style: simple
          schema:
            type: string
            example: da7d5b0e18a84aeda961c0c31b75c2a9
        - name: Merchant-Serial-Number
          in: header
          description: >-
            The Merchant Serial Number (MSN) is a unique ID for the sale unit
            that this payment is made for.

            This is a required parameter if you are a partner making payments on
            behalf of a merchant.

            The partner must use the merchant's MSN (not the partner's MSN).

            This parameter is optional, and recommended, for regular Vipps
            merchants making payments for themselves.
          style: simple
          schema:
            type: string
            example: '654321'
        - name: Vipps-System-Name
          in: header
          description: |-
            The name of the ecommerce solution.
            One word in lowercase letters is good.
            See [HTTP headers](/docs/knowledge-base/http-headers/).
          style: simple
          schema:
            maxLength: 30
            type: string
            example: woocommerce
        - name: Vipps-System-Version
          in: header
          description: |-
            The version number of the ecommerce solution.
            See [HTTP headers](/docs/knowledge-base/http-headers/).
          style: simple
          schema:
            maxLength: 30
            type: string
            example: 5.4.0
        - name: Vipps-System-Plugin-Name
          in: header
          description: |-
            The name of the ecommerce plugin (if applicable).
            One word in lowercase letters is good.
            See [HTTP headers](/docs/knowledge-base/http-headers/).
          style: simple
          schema:
            maxLength: 30
            type: string
            example: vipps-woocommerce
        - name: Vipps-System-Plugin-Version
          in: header
          description: |-
            The version number of the ecommerce plugin (if applicable).
            See [HTTP headers](/docs/knowledge-base/http-headers/).
          style: simple
          schema:
            maxLength: 30
            type: string
            example: 1.2.1
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    post:
      tags:
        - v1
      summary: Register webhook
      description: >-
        Register a new webhook.

        There is a limit to the number of webhooks that can be registered per
        event, see the API guide for more information.
      parameters:
        - name: Ocp-Apim-Subscription-Key
          in: header
          description: |-
            The subscription key.
            See [API keys](/docs/knowledge-base/api-keys/).
          required: true
          style: simple
          schema:
            type: string
            example: da7d5b0e18a84aeda961c0c31b75c2a9
        - name: Merchant-Serial-Number
          in: header
          description: >-
            The Merchant Serial Number (MSN) is a unique ID for the sale unit
            that this payment is made for.

            This is a required parameter if you are a partner making payments on
            behalf of a merchant.

            The partner must use the merchant's MSN (not the partner's MSN).

            This parameter is optional, and recommended, for regular Vipps
            merchants making payments for themselves.
          style: simple
          schema:
            type: string
            example: '654321'
        - name: Vipps-System-Name
          in: header
          description: |-
            The name of the ecommerce solution.
            One word in lowercase letters is good.
            See [HTTP headers](/docs/knowledge-base/http-headers/).
          style: simple
          schema:
            maxLength: 30
            type: string
            example: woocommerce
        - name: Vipps-System-Version
          in: header
          description: |-
            The version number of the ecommerce solution.
            See [HTTP headers](/docs/knowledge-base/http-headers/).
          style: simple
          schema:
            maxLength: 30
            type: string
            example: 5.4.0
        - name: Vipps-System-Plugin-Name
          in: header
          description: |-
            The name of the ecommerce plugin (if applicable).
            One word in lowercase letters is good.
            See [HTTP headers](/docs/knowledge-base/http-headers/).
          style: simple
          schema:
            maxLength: 30
            type: string
            example: vipps-woocommerce
        - name: Vipps-System-Plugin-Version
          in: header
          description: |-
            The version number of the ecommerce plugin (if applicable).
            See [HTTP headers](/docs/knowledge-base/http-headers/).
          style: simple
          schema:
            maxLength: 30
            type: string
            example: 1.2.1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterResponse'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /v1/webhooks/{id}:
    delete:
      tags:
        - v1
      summary: Delete a webhook
      parameters:
        - name: id
          in: path
          required: true
          style: simple
          schema:
            type: string
            format: uuid
        - name: Ocp-Apim-Subscription-Key
          in: header
          description: The subscription key
          required: true
          style: simple
          schema:
            type: string
            example: da7d5b0e18a84aeda961c0c31b75c2a9
        - name: Merchant-Serial-Number
          in: header
          description: >-
            The Merchant Serial Number (MSN) is a unique ID for the sale unit
            that this payment is made for.

            This is a required parameter if you are a partner making payments on
            behalf of a merchant.

            The partner must use the merchant's MSN (not the partner's MSN).

            This parameter is optional, and recommended, for regular Vipps
            merchants making payments for themselves.
          style: simple
          schema:
            type: string
            example: '654321'
        - name: Vipps-System-Name
          in: header
          description: |-
            The name of the ecommerce solution.
            One word in lowercase letters is good.
            See [HTTP headers](/docs/knowledge-base/http-headers/).
          style: simple
          schema:
            maxLength: 30
            type: string
            example: woocommerce
        - name: Vipps-System-Version
          in: header
          description: |-
            The version number of the ecommerce solution.
            See [HTTP headers](/docs/knowledge-base/http-headers/).
          style: simple
          schema:
            maxLength: 30
            type: string
            example: 5.4.0
        - name: Vipps-System-Plugin-Name
          in: header
          description: |-
            The name of the ecommerce plugin (if applicable).
            One word in lowercase letters is good.
            See [HTTP headers](/docs/knowledge-base/http-headers/).
          style: simple
          schema:
            maxLength: 30
            type: string
            example: vipps-woocommerce
        - name: Vipps-System-Plugin-Version
          in: header
          description: |-
            The version number of the ecommerce plugin (if applicable).
            See [HTTP headers](/docs/knowledge-base/http-headers/).
          style: simple
          schema:
            maxLength: 30
            type: string
            example: 1.2.1
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    ExtraDetail:
      required:
        - name
        - reason
      type: object
      properties:
        name:
          type: string
          example: url
        reason:
          type: string
          example: The property is required and cannot be null or empty.
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
          example: 00-bb841c551513e233de8a01472013fa9f-542c71e40916a6ce-00
        title:
          type: string
          nullable: true
          example: Bad Request
        status:
          type: integer
          format: int32
          nullable: true
          example: 400
        detail:
          type: string
          nullable: true
          example: One or more validation errors occurred.
        instance:
          type: string
          nullable: true
          example: /v1/webhooks
        traceId:
          type: string
          nullable: true
          example: 00-bb841c551513e233de8a01472013fa9f-542c71e40916a6ce-00
        extraDetails:
          type: array
          items:
            $ref: '#/components/schemas/ExtraDetail'
          nullable: true
      additionalProperties: false
    QueryResponse:
      required:
        - webhooks
      type: object
      properties:
        webhooks:
          type: array
          items:
            $ref: '#/components/schemas/Webhook'
      additionalProperties: false
    RegisterRequest:
      required:
        - events
        - url
      type: object
      properties:
        url:
          type: string
          description: >-
            The URL that updates should be sent to.

            Must be a valid, world-reachable URL.

            The URL must use HTTPS.

            The URL must respond with a 2XX HTTP status code, like `HTTP 200
            OK`.

            Can not be a URL that redirects to a different URL.

            We don't send requests to all ports, so to be safe use common ports
            such as: 80, 443, 8080.
          format: uri
          example: https://example.com/webhook-callback
        events:
          type: array
          items:
            type: string
          description: >-
            See [Webhooks API Events](/docs/APIs/webhooks-api/events/) for
            details.
          example:
            - epayments.payment.captured.v1
            - epayments.payment.created.v1
      additionalProperties: false
    RegisterResponse:
      required:
        - id
        - secret
      type: object
      properties:
        id:
          type: string
          description: The ID of the webhook URL. Used to retrieve and delete it later.
          format: uuid
        secret:
          type: string
          description: >-
            The secret of the webhook URL, used in the `Authorization` header

            for the API request to the webhook URL.

            See: [Request
            authentication](/docs/APIs/webhooks-api/request-authentication/).
          example: 090a478d-37ff-4e77-970e-d457aeb26a3a
      additionalProperties: false
    Webhook:
      required:
        - events
        - id
        - url
      type: object
      properties:
        id:
          type: string
          description: The ID of the webhook URL.
          format: uuid
        url:
          type: string
          format: uri
          example: https://example.com/callbacks
        events:
          type: array
          items:
            type: string
          example:
            - service.payment.captured.v1
            - service.payment.created.v2
      additionalProperties: false
  securitySchemes:
    Bearer-Authorization:
      type: apiKey
      description: Access bearer token (JWT)
      name: Authorization
      in: header
security:
  - Bearer-Authorization: []
