Webhooks API

webhooks-api-definition.yaml

openapi: 3.0.0
servers:
  - description: Conekta API
    url: 'https://api.conekta.io'
info:
  description: This documents Conekta's public API V2.0.0.
  version: 1.0.1-oas3
  title: Conekta Payment API
  contact:
    email: [email protected]
    name: Leo Fischer
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
tags:
  - name: Balance
    description: Operations to review one's balane
paths:
  /webhooks:
    get:
      tags:
        - Webhooks
      summary: Retrieve a list of Webhooks
      operationId: listWebhooks
      description: |
        Retrieve webhooks from Conekta
      parameters:
        - in: query
          name: search
          description: An additional parameter to search for
          required: false
          schema:
            type: string
            minLength: 0
            maxLength: 50
        - in: query
          name: previous
          description: id of the previous record
          required: false
          schema:
            type: string
            minLength: 0
            maxLength: 50
        - in: query
          name: next
          description: id of next record
          required: false
          schema:
            type: string
            minLength: 0
            maxLength: 50
        - in: query
          name: limit
          description: maximum number of records to return
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 50
      responses:
        '200':
          description: Webhook search results matching criteria
          content:
            application/vnd.conekta-v2.0.0+json:
              schema:
                $ref: '#/components/schemas/WebhookListResponse'
        'default':
          description: 'Error: Error could not be processed'
          content:
            application/vnd.conekta-v2.0.0+json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - Webhooks
      summary: Create a webhook
      operationId: createWebhook
      description: Creates an Webhook in the System
      responses:
        '200':
          description: 'Success: Webhook created.'
          content:
            application/vnd.conekta-v2.0.0+json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
        'default':
          description: 'Error: Error could not be processed'
          content:
            application/vnd.conekta-v2.0.0+json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRequest'
        description: Create a webhook
  /webhooks/{webhookId}:
    get:
      tags:
        - Webhooks
      summary: Retrieve a single Webhook by id
      operationId: getWebhook
      description: |
        Retrieves an Webhook from Conekta
      parameters:
        - in: path
          name: webhookId
          schema:
            type: string
            minLength: 21
            maxLength: 50
          required: true
          description: The id of the Webhook to be retrieved
      responses:
        '200':
          description: Webhook search results matching criteria
          content:
            application/vnd.conekta-v2.0.0+json:
              schema:
                $ref: '#/components/schemas/WebhookListResponse'
        'default':
          description: 'Error: Error could not be processed'
          content:
            application/vnd.conekta-v2.0.0+json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
        - Webhooks
      summary: Update a webhook
      operationId: updateWebhook
      description: Updates an Webhook in the System
      parameters:
        - in: path
          name: webhookId
          schema:
            type: string
            minLength: 21
            maxLength: 50
          required: true
          description: The id of the Webhook to be modified
      responses:
        '200':
          description: 'Success: Webhook updated'
          content:
            application/vnd.conekta-v2.0.0+json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
        'default':
          description: 'Error: Error could not be processed'
          content:
            application/vnd.conekta-v2.0.0+json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookUpdateRequest'
        description: Update a webhook
    delete:
      tags:
        - Webhooks
      summary: Delete a webhook
      operationId: deleteWebhook
      description: Deletes an Webhook
      parameters:
        - in: path
          name: webhookId
          schema:
            type: string
            minLength: 21
            maxLength: 50
          required: true
          description: The id of the Webhook to be deleted
      responses:
        '200':
          description: 'Success: Webhook updated'
          content:
            application/vnd.conekta-v2.0.0+json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
        'default':
          description: 'Error: Error could not be processed'
          content:
            application/vnd.conekta-v2.0.0+json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  schemas:
    Error:
      type: object
      required:
        - object
        - type
        - log_id
        - data
        - details
      properties:
        object:
          type: string
          example: error
          description: The type of object being returned by Conekta
        type:
          type: string
          description: The type of error being returned
          enum:
            - malformed_request_error
            - authentication_Error
            - processing_error
            - conflict_error
            - parameter_validation_error
            - precondition_required_error
            - api_error
        log_id:
          type: string
          description: The id of the log associated with this request
          example: 5ecae6ec82c2720ffe900890
        data:
          description: The object modified by this request (if applicable)
          type: object
        details:
          type: array
          description: The details of the error being thrown
          items:
            type: object
            properties:
              message:
                type: string
                description: A developer friendly message giving details about the nature of the error
                example: Amount must be greater than zero
              debug_message:
                type: string
                description: A human readable message which can be presented to the end user.
                example: Please add something to your card before proceeding
              code:
                type: string
                description: A specific error code, which can be reused to provide machine readable / custom translations. 
                example: error.parameter_validation.number_is_not_greater_than
              param:
                type: string
                description: The parameter of the request which was marked invalid, this only applies to parameter validation errors.
                example: charges.token_id
    WebhookRequest:
      type: object
      required:
        - url
      properties:
        certificate:
          type: string
          minLength: 2
          maxLength: 1000
          description: A public PGP key to authenticate the endpoint
          example: https://www.example.com/notifications/conekta
        subscribed_events:
          type: array
          items:
            type: string
            minLength: 2
            maxLength: 100
          description: The type of events which will be notified to this webhook
          example: false
        synchronous:
          type: boolean
          description: whether this is used for synchronous payment approvals (e.g. oxxo and spei recurring payments)
          example: false
        url:
          type: string
          minLength: 2
          maxLength: 250
          description: The url of the endpoint
          example: https://www.example.com/notifications/conekta
    WebhookUpdateRequest:
      type: object
      properties:
        certificate:
          type: string
          minLength: 2
          maxLength: 1000
          description: A public PGP key to authenticate the endpoint
          example: https://www.example.com/notifications/conekta
        subscribed_events:
          type: array
          items:
            type: string
            minLength: 2
            maxLength: 100
          description: The type of events which will be notified to this webhook
          example: false
        synchronous:
          type: boolean
          description: whether this is used for synchronous payment approvals (e.g. oxxo and spei recurring payments)
          example: false
    WebhookResponse:
      type: object
      required:
        - created_at
        - id
        - livemode
        - object
        - status
        - subscribed_events
        - synchronous
        - updated_at
        - url
      properties:
        certificate_sha256:
          type: string
          example: "cc64accc19cd909dc2d09ae5cf8b2a449e540e6c2c467413b77f91922ac87673
            5f4d3867772a81834e9b77f613b33646c7043b96b566313ea0e56ad0e01f24d1
            27de9a9ea544e344af9890f85f606e1fd68b9da15a7a14fe7cb5b084159c78ca
            5d4a72f4665d82f672e71415c719a47872c72bc62f58978bd9b35cca4d6dd517
            557a696a0187d34f8da2dea1c58baafdefde3156995050e6cea67c75ea5c6f03
            30e9fd206e27b2bf8d80fefc1b3911335b6d4e66a4aee677a58b0a2eae85661d
            f429d01ca0a513ed4d3d1dd4961077f64b4c222b57e03c33fea7480893b3ea85
            99435a6aefecac59441a947d51059c9dae4fb38fd8be8d124f733bbc6ade5cd0
            ada4ea78f3b27b942e23e013124c3faac22dd9e286773afe9c9a51943d865a90
            59f2638df61dadbe22f8132c69f323e07c28b0a181d933b7705b6d5ed6092e14"
          description: A sha256 of the webhook encryption key (if given)
        created_at:
          type: integer
          minimum: 0
          maximum: 100000000000
          example: 1590586101
          description: The unix timestamp at which the resource was created.
        deleted:
          type: boolean
          description: Whether or not the resource has been deleted
        id:
          type: string
          minLength: 21
          maxLength: 50
          description: The resource's unique identifier.
        livemode:
          type: boolean
          description: The livemode of the charge, true if production and false if in sandbox.
        object:
          type: string
          example: webhook
          description: The type of object being returned, in this case a webhook.
        status:
          type: string
          enum:
            - failing
            - listening
            - pinging
            - unresponsive
          description: The status of the webhook
        synchronous:
          type: boolean
          description: whether this is used for synchronous payment approvals (e.g. oxxo and spei recurring payments)
          example: false
        subscribed_events:
          type: array
          items:
            type: string
            minLength: 2
            maxLength: 100
          description: The type of events which will be notified to this webhook
          example: false
        updated_at:
          type: integer
          minimum: 0
          maximum: 100000000000
          example: 1590586201
          description: The unix timestamp when the webhook was last updated.
        url:
          type: string
          minLength: 2
          maxLength: 250
          description: The url of the endpoint
          example: https://www.example.com/notifications/conekta
    WebhookListResponse:
      type: object
      required:
        - next_page_url
        - previous_page_url
        - has_more
        - object
        - data
      properties:
        next_page_url:
          type: string
          format: uri
          example: 'https://api.conekta.io/webhooks?next=webhook_zzmjKsnM9oacyCwV3'
          description: The next page in the list being iterated.
        previous_page_url:
          type: string
          format: uri
          example: >-
            https://api.conekta.io/webhooks?previous=webhook_2nk1bQEXYFLMyMFDg
          description: The previous page in the list being iterated.
        has_more:
          type: boolean
          example: true
          description: Whether there are other records to be paginated
        object:
          type: string
          example: list
          description: The type of object being returned, in this case a list.
        data:
          description: The elements of the list being retrieved.
          type: array
          items:
            $ref: '#/components/schemas/WebhookResponse'