openapi: 3.0.1
info:
  description: Webhooks API
  title: Webhooks API
  version: v1.0.0
paths:
  /healthcheck:
    get:
      operationId: healthCheck
      responses:
        "200":
          content:
            application/json:
              schema:
                type: string
                example:
                  database:
                    healthy: true
                    message: Healthy
                  ping:
                    healthy: true
                    message: Healthy
                  hibernate:
                    healthy: true
                    message: Healthy
                  deadlocks:
                    healthy: true
                    message: Healthy
                  sqsQueue:
                    healthy: true
                    message: Healthy
          description: OK
        "503":
          description: Service unavailable. If any healthchecks fail
      summary: "Healthcheck endpoint for webhooks. Check database, deadlocks, hibernate\
        \ and ping"
      tags:
      - Other
  /v1/webhook:
    get:
      operationId: getWebhooks
      parameters:
      - description: Set to `true` to return live webhooks for service.
        example: true
        in: query
        name: live
        required: true
        schema:
          type: boolean
      - description: Service external ID. Required when override_service_id_restriction
          is not `true`
        example: eo29upsdkjlk3jpwjj2dfn12
        in: query
        name: service_id
        schema:
          type: string
      - description: Gateway account ID. Required when override_service_id_restriction
          is not `true`
        example: 100
        in: query
        name: gateway_account_id
        schema:
          type: string
      - description: "Set to true to list all webhooks. if 'true', service_id is not\
          \ permitted"
        example: true
        in: query
        name: override_service_id_restriction
        schema:
          type: boolean
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WebhookResponse"
          description: OK
        "400":
          description: For invalid query params
      summary: List webhooks for a service external ID or all webhooks
      tags:
      - Webhooks
    post:
      operationId: createWebhook
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWebhookRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookResponse"
          description: OK
        "400":
          description: "Invalid payload (ex: non existent event type)"
        "422":
          description: Missing required parameters
      summary: Create new webhook
      tags:
      - Webhooks
  /v1/webhook/tasks/delete_messages:
    post:
      description: Task to delete webhook messages older than a default of seven days
        (this is configurable).
      operationId: expireWebhookMessages
      responses:
        "200":
          description: OK
        "500":
          description: Internal server error
      summary: Deletes webhook messages
      tags:
      - Webhooks
  /v1/webhook/{webhookExternalId}:
    get:
      operationId: getWebhookByExternalId
      parameters:
      - example: gh0d0923jpsjdf0923jojlsfgkw3seg
        in: path
        name: webhookExternalId
        required: true
        schema:
          type: string
      - example: eo29upsdkjlk3jpwjj2dfn12
        in: query
        name: service_id
        schema:
          type: string
      - example: 100
        in: query
        name: gateway_account_id
        schema:
          type: string
      - description: "If false, the service_id and gateway_account_id must be specified"
        example: false
        in: query
        name: override_account_or_service_id_restriction
        schema:
          type: boolean
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookResponse"
          description: OK
        "404":
          description: Not found
      summary: "Get webhook by external ID, service ID and gateway account ID (query\
        \ param)"
      tags:
      - Webhooks
    patch:
      description: "Allows patching `description, callback_url, status, subscriptions`"
      operationId: updateWebhook
      parameters:
      - example: gh0d0923jpsjdf0923jojlsfgkw3seg
        in: path
        name: webhookExternalId
        required: true
        schema:
          type: string
      - example: eo29upsdkjlk3jpwjj2dfn12
        in: query
        name: service_id
        required: true
        schema:
          type: string
      - example: 100
        in: query
        name: gateway_account_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/JsonNode"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookResponse"
          description: OK
        "400":
          description: Invalid payload
      summary: Update webhook
      tags:
      - Webhooks
  /v1/webhook/{webhookExternalId}/message:
    get:
      operationId: getWebhookMessages
      parameters:
      - example: gh0d0923jpsjdf0923jojlsfgkw3seg
        in: path
        name: webhookExternalId
        required: true
        schema:
          type: string
      - example: 1
        in: query
        name: page
        schema:
          type: integer
          format: int32
      - description: "If supplied, will only list messages with this delivery status"
        example: SUCCESSFUL
        in: query
        name: status
        schema:
          type: string
          enum:
          - PENDING
          - SUCCESSFUL
          - FAILED
          - WILL_NOT_SEND
      - description: The external ID of the resource (e.g. the payment) to get messages
          for
        example: 2qmfui4aklat22u0jab98m0ou4
        in: query
        name: resource_id
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookMessageSearchResponse"
          description: OK
      summary: Get webhook messages by webhook external ID
      tags:
      - Webhooks
  /v1/webhook/{webhookExternalId}/message/{webhookMessageExternalId}:
    get:
      operationId: getWebhookMessage
      parameters:
      - in: path
        name: webhookExternalId
        required: true
        schema:
          type: string
          example: gh0d0923jpsjdf0923jojlsfgkw3seg
      - in: path
        name: webhookMessageExternalId
        required: true
        schema:
          type: string
          example: s0wjen129ejalk21nfjkdknf1jejklh
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookMessageResponse"
          description: OK
      summary: Get messages by webhook external ID and message ID
      tags:
      - Webhooks
  /v1/webhook/{webhookExternalId}/message/{webhookMessageExternalId}/attempt:
    get:
      operationId: getWebhookMessageAttempts
      parameters:
      - in: path
        name: webhookExternalId
        required: true
        schema:
          type: string
          example: gh0d0923jpsjdf0923jojlsfgkw3seg
      - in: path
        name: webhookMessageExternalId
        required: true
        schema:
          type: string
          example: s0wjen129ejalk21nfjkdknf1jejklh
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WebhookDeliveryQueueResponse"
          description: OK
      summary: Get message attempts for webhook external ID and message ID
      tags:
      - Webhooks
  /v1/webhook/{webhookExternalId}/signing-key:
    get:
      operationId: getSigningKeyByExternalId
      parameters:
      - example: gh0d0923jpsjdf0923jojlsfgkw3seg
        in: path
        name: webhookExternalId
        required: true
        schema:
          type: string
      - example: 100
        in: query
        name: gateway_account_id
        required: true
        schema:
          type: string
      - example: eo29upsdkjlk3jpwjj2dfn12
        in: query
        name: service_id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SigningKeyResponse"
          description: OK
        "404":
          description: Not found
      summary: Get webhook signing key by external ID
      tags:
      - Webhooks
    post:
      operationId: regenerateSigningKey
      parameters:
      - example: gh0d0923jpsjdf0923jojlsfgkw3seg
        in: path
        name: webhookExternalId
        required: true
        schema:
          type: string
      - example: 100
        in: query
        name: gateway_account_id
        required: true
        schema:
          type: string
      - example: eo29upsdkjlk3jpwjj2dfn12
        in: query
        name: service_id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SigningKeyResponse"
          description: OK
        "404":
          description: Not found
      summary: Regenerate webhook signing key
      tags:
      - Webhooks
components:
  schemas:
    CreateWebhookRequest:
      type: object
      properties:
        callback_url:
          type: string
          example: https://example.com
          maxLength: 2048
          minLength: 0
        description:
          type: string
          example: Webhook description
        gateway_account_id:
          type: string
          example: "100"
          minLength: 1
        live:
          type: boolean
        service_id:
          type: string
          example: eo29upsdkjlk3jpwjj2dfn12
          maxLength: 32
          minLength: 0
        subscriptions:
          type: array
          items:
            type: string
            enum:
            - card_payment_started
            - card_payment_succeeded
            - card_payment_captured
            - card_payment_refunded
            - card_payment_failed
            - card_payment_expired
            example: card_payment_started
      required:
      - callback_url
      - gateway_account_id
      - live
      - service_id
    JsonNode:
      type: object
      example:
        path: description
        op: replace
        value: new description
    SigningKeyResponse:
      type: object
      properties:
        signing_key:
          type: string
          example: webhook_live_d0sjdkwn1edjals029dd91odndi21fn
    WebhookDeliveryQueueResponse:
      type: object
      properties:
        created_date:
          type: string
          format: date-time
        response_time:
          type: integer
          format: int64
          example: 23
        result:
          type: string
          example: 200 OK
        send_at:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - PENDING
          - SUCCESSFUL
          - FAILED
          - WILL_NOT_SEND
          example: SUCCESSFUL
        status_code:
          type: integer
          format: int32
          example: 200
    WebhookMessageResponse:
      type: object
      properties:
        created_date:
          type: string
          format: date-time
        event_date:
          type: string
          format: date-time
        event_type:
          type: string
          enum:
          - card_payment_started
          - card_payment_succeeded
          - card_payment_captured
          - card_payment_refunded
          - card_payment_failed
          - card_payment_expired
          example: card_payment_started
        external_id:
          type: string
          example: s0wjen129ejalk21nfjkdknf1jejklh
        last_delivery_status:
          type: string
          enum:
          - PENDING
          - SUCCESSFUL
          - FAILED
          - WILL_NOT_SEND
        latest_attempt:
          $ref: "#/components/schemas/WebhookDeliveryQueueResponse"
        resource:
          $ref: "#/components/schemas/JsonNode"
        resource_id:
          type: string
          example: payment-external-id-123
        resource_type:
          type: string
          example: payment
    WebhookMessageSearchResponse:
      type: object
      properties:
        count:
          type: integer
          format: int32
          description: The number of results in the current page
          example: 10
        page:
          type: integer
          format: int32
          description: The page of results
          example: 1
        results:
          type: array
          items:
            $ref: "#/components/schemas/WebhookMessageResponse"
        total:
          type: integer
          format: int64
          description: The total number of results
          example: 100
    WebhookResponse:
      type: object
      properties:
        callback_url:
          type: string
          example: https://example.com
        created_date:
          type: string
          format: date-time
          example: 2022-04-05T17:07:15.281Z
        description:
          type: string
          example: Webhook description
        external_id:
          type: string
          example: gh0d0923jpsjdf0923jojlsfgkw3seg
        gateway_account_id:
          type: string
          example: "100"
        live:
          type: boolean
        service_id:
          type: string
          example: eo29upsdkjlk3jpwjj2dfn12
        status:
          type: string
          enum:
          - ACTIVE
          - INACTIVE
          example: ACTIVE
        subscriptions:
          type: array
          items:
            type: string
            enum:
            - card_payment_started
            - card_payment_succeeded
            - card_payment_captured
            - card_payment_refunded
            - card_payment_failed
            - card_payment_expired
            example: card_payment_started