webhooks.yaml

openapi: 3.1.0
info:
  title: Rafiki Webhooks
  version: 1.1.0
  description: 'Webhook Events fired by Rafiki'
  contact:
    email: tech@interledger.org
servers:
  - url: 'https://account-servicing-entity.com/webhooks'
webhooks:
  incomingPaymentCompleted:
    post:
      requestBody:
        description: Notify account servicing entity that an incoming payment was completed and funds should now be withdrawn.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/incomingPaymentEvent'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  incomingPaymentExpired:
    post:
      requestBody:
        description: Notify account servicing entity that an incoming payment has expired and funds should now be withdrawn.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/incomingPaymentEvent'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  outgoingPaymentCreated:
    post:
      requestBody:
        description: Notify account servicing entity that an outgoing payment was created and should now be funded.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/outgoingPaymentEvent'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  outgoingPaymentCompleted:
    post:
      requestBody:
        description: Notify account servicing entity that an outgoing payment completed. Remaining funds should be withdrawn.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/outgoingPaymentEvent'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  outgoingPaymentFailed:
    post:
      requestBody:
        description: Notify account servicing entity that an outgoing payment failed and won't be retried. Funds should be withdrawn.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/outgoingPaymentEvent'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  walletAddressNotFound:
    post:
      requestBody:
        description: Notify account servicing entity to create a wallet address if it can find a corresponding account in their system.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/walletAddressNotFound'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  webMonetization:
    post:
      requestBody:
        description: Notify account servicing entity that a Web Monetization payment was received and funds should be withdrawn.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webMonetizationEvent'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  assetLiquidity:
    post:
      requestBody:
        description: Notify account servicing entity that asset liquidity is low.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/liquidityEvent'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
  peerLiquidity:
    post:
      requestBody:
        description: Notify account servicing entity that peer liquidity is low.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/liquidityEvent'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully

components:
  schemas:
    incomingPaymentEvent:
      required:
        - id
        - type
        - data
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - incoming_payment.created
            - incoming_payment.completed
            - incoming_payment.expired
        data:
          type: object
          required:
            - id
            - walletAddressId
            - createdAt
            - updatedAt
            - expiresAt
            - receivedAmount
            - completed
          properties:
            id:
              type: string
              format: uuid
            walletAddressId:
              type: string
              format: uuid
            client:
              type: string
              format: url
            completed:
              type: boolean
            incomingAmount:
              $ref: ./schemas.yaml#/components/schemas/amount
            receivedAmount:
              $ref: ./schemas.yaml#/components/schemas/amount
            metadata:
              type: object
              additionalProperties: true
            createdAt:
              type: string
              format: date-time
            updatedAt:
              type: string
              format: date-time
            expiresAt:
              type: string
              format: date-time
      additionalProperties: false
    outgoingPaymentEvent:
      required:
        - id
        - type
        - data
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - outgoing_payment.created
            - outgoing_payment.completed
            - outgoing_payment.failed
        data:
          type: object
          required:
            - id
            - walletAddressId
            - createdAt
            - updatedAt
            - expiresAt
            - debitAmount
            - receiveAmount
            - state
            - stateAttempts
            - balance
            - receiver
          properties:
            id:
              type: string
              format: uuid
            walletAddressId:
              type: string
              format: uuid
            client:
              type: string
              format: url
            state:
              type: string
              enum:
                - FUNDING
                - SENDING
                - FAILED
                - COMPLETED
            receiver:
              type: string
              format: uri
            debitAmount:
              $ref: ./schemas.yaml#/components/schemas/amount
            sentAmount:
              $ref: ./schemas.yaml#/components/schemas/amount
            metadata:
              type: object
              additionalProperties: true
            createdAt:
              type: string
              format: date-time
            updatedAt:
              type: string
              format: date-time
            expiresAt:
              type: string
              format: date-time
            error:
              type: string
            stateAttempts:
              type: integer
            balance:
              type: string
              format: uint64
            peerId:
              type: string
              format: uuid
      additionalProperties: false
    walletAddressNotFound:
      required:
        - id
        - type
        - data
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - wallet_address.not_found
        data:
          type: object
          required:
            - walletAddressUrl
          properties:
            walletAddressUrl:
              type: string
      additionalProperties: false
    webMonetizationEvent:
      required:
        - id
        - type
        - data
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - wallet_address.web_monetization
        data:
          type: object
          required:
            - walletAddress
          properties:
            walletAddress:
              type: object
              required:
                - id
                - createdAt
                - received
              properties:
                id:
                  type: string
                  format: uuid
                createdAt:
                  type: string
                  format: date-time
                receivedAmount:
                  $ref: ./schemas.yaml#/components/schemas/amount
      additionalProperties: false
    liquidityEvent:
      required:
        - id
        - type
        - data
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - asset.liquidity_low
            - peer.liquidity_low
        data:
          type: object
          required:
            - id
            - asset
            - liquidityThreshold
            - balance
          properties:
            id:
              type: string
              format: uuid
            asset:
              $ref: '#/components/schemas/asset'
            liquidityThreshold:
              type: string
            balance:
              type: string
      additionalProperties: false
    asset:
      required:
        - id
        - code
        - scale
      properties:
        id:
          type: string
          format: uuid
        code:
          type: string
        scale:
          type: number
      additionalProperties: false