openapi: 3.0.3
info:
  title: Paypal Subscriptions Authorizations Webhooks-Events API
  description: You can use billing plans and subscriptions to create subscriptions that process recurring PayPal payments for physical or digital goods, or services. A plan includes pricing and billing cycle information that defines the amount and frequency of charge for a subscription. You can also define a fixed plan, such as a $5 basic plan or a volume- or graduated-based plan with pricing tiers based on the quantity purchased. For more information, see <a href="/docs/subscriptions/">Subscriptions Overview</a>.
  version: '1.6'
  contact: {}
servers:
- url: https://api-m.sandbox.paypal.com
  description: PayPal Sandbox Environment
- url: https://api-m.paypal.com
  description: PayPal Live Environment
tags:
- name: Webhooks-Events
  description: Use the `/webhooks-events` resource to list, show details for, and resend event notifications.
paths:
  /v1/notifications/webhooks-events:
    get:
      summary: Paypal List event notifications
      description: Lists webhooks event notifications. Use query parameters to filter the response.
      operationId: webhooks-events.list
      responses:
        '200':
          description: A successful request returns the HTTP `200 OK` status code and a JSON response body that lists webhooks event notifications.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventList'
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      parameters:
      - $ref: '#/components/parameters/page_size'
      - $ref: '#/components/parameters/start_time'
      - $ref: '#/components/parameters/end_time'
      - $ref: '#/components/parameters/transaction_id'
      - $ref: '#/components/parameters/event_type'
      security:
      - Oauth2:
        - https://uri.paypal.com/services/applications/webhooks
      tags:
      - Webhooks-Events
  /v1/notifications/webhooks-events/{event_id}:
    get:
      summary: Paypal Show event notification details
      description: Shows details for a webhooks event notification, by ID.
      operationId: webhooks-events.get
      responses:
        '200':
          description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows webhooks event notification details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event'
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      parameters:
      - $ref: '#/components/parameters/event_id'
      security:
      - Oauth2:
        - https://uri.paypal.com/services/applications/webhooks
      tags:
      - Webhooks-Events
  /v1/notifications/webhooks-events/{event_id}/resend:
    post:
      summary: Paypal Resend event notification
      description: Resends a webhook event notification, by ID. Any pending notifications are not resent.
      operationId: webhooks-events.resend
      responses:
        '202':
          description: A successful request returns the HTTP `202 Accepted` status code and a JSON response body that shows webhook event notification details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event'
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      parameters:
      - $ref: '#/components/parameters/event_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/event_resend'
      security:
      - Oauth2:
        - https://uri.paypal.com/services/applications/webhooks
      tags:
      - Webhooks-Events
components:
  schemas:
    event_resend:
      type: object
      title: Event Resend
      description: Resends a webhook event notification, by ID.
      properties:
        webhook_ids:
          type: array
          maxItems: 500
          description: An array of webhook account IDs.
          items:
            type: string
            description: The ID of the webhook event notification to resend.
    event:
      type: object
      title: Event
      description: A webhook event notification.
      properties:
        id:
          type: string
          description: The ID of the webhook event notification.
          readOnly: true
        create_time:
          type: string
          format: date-time
          description: The date and time when the webhook event notification was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
          readOnly: true
        resource_type:
          type: string
          description: The name of the resource related to the webhook notification event.
          readOnly: true
        event_version:
          $ref: '#/components/schemas/event_version'
        event_type:
          type: string
          description: The event that triggered the webhook event notification.
          readOnly: true
        summary:
          type: string
          description: A summary description for the event notification.
          readOnly: true
        resource_version:
          $ref: '#/components/schemas/resource_version'
        resource:
          type: object
          title: Resource
          description: The resource that triggered the webhook event notification.
          readOnly: true
          additionalProperties: true
        links:
          type: array
          description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).
          readOnly: true
          items:
            $ref: '#/components/schemas/link_description'
            readOnly: true
    EventList:
      type: object
      title: Event List
      description: A list of webhooks events.
      properties:
        events:
          type: array
          description: An array of webhooks events.
          items:
            $ref: '#/components/schemas/event'
        count:
          type: integer
          description: The number of items in each range of results. Note that the response might have fewer items than the requested `page_size` value.
        links:
          type: array
          description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).
          readOnly: true
          items:
            $ref: '#/components/schemas/link_description'
    event_version:
      type: string
      title: Event Version
      description: The event version in the webhook notification.
      deprecated: true
      pattern: ^([0-9]+.[0-9]+)$
    error:
      type: object
      title: Error
      description: The error details.
      properties:
        name:
          type: string
          description: The human-readable, unique name of the error.
        message:
          type: string
          description: The message that describes the error.
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        information_link:
          type: string
          description: The information link, or URI, that shows detailed information about this error for the developer.
          readOnly: true
        details:
          type: array
          description: An array of additional details about the error.
          items:
            $ref: '#/components/schemas/error_details-2'
        links:
          type: array
          description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).
          readOnly: true
          items:
            $ref: '#/components/schemas/link_description'
            readOnly: true
      required:
      - name
      - message
      - debug_id
    link_description:
      type: object
      title: Link Description
      description: The request-related [HATEOAS link](/docs/api/reference/api-responses/#hateoas-links) information.
      required:
      - href
      - rel
      properties:
        href:
          type: string
          description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
        rel:
          type: string
          description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
        method:
          type: string
          description: The HTTP method required to make the related call.
          enum:
          - GET
          - POST
          - PUT
          - DELETE
          - HEAD
          - CONNECT
          - OPTIONS
          - PATCH
    resource_version:
      title: Resource Version
      description: The resource version in the webhook notification.
      type: string
      pattern: ^([0-9]+.[0-9]+)$
    error_details-2:
      title: Error Details
      type: object
      description: The error details. Required for client-side `4XX` errors.
      properties:
        field:
          type: string
          description: The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.
        value:
          type: string
          description: The value of the field that caused the error.
        location:
          type: string
          description: The location of the field that caused the error. Value is `body`, `path`, or `query`.
          default: body
        issue:
          type: string
          description: The unique, fine-grained application-level error code.
        description:
          type: string
          description: The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.
      required:
      - issue
  parameters:
    page_size:
      name: page_size
      in: query
      description: The number of webhook event notifications to return in the response.
      schema:
        type: integer
        default: 10
    event_id:
      name: event_id
      in: path
      description: The ID of the webhook event notification to resend.
      required: true
      schema:
        type: string
        maxLength: 50
        pattern: ^[a-zA-Z0-9]+$
    transaction_id:
      name: transaction_id
      in: query
      description: Filters the response to a single transaction, by ID.
      schema:
        type: string
    end_time:
      name: end_time
      in: query
      description: 'Filters the webhook event notifications in the response to those created on or after the `start_time` and on or before this date and time. Both values are in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6) format. Example: `end_time=2013-03-06T11:00:00Z`.'
      schema:
        type: string
    event_type:
      name: event_type
      in: query
      description: Filters the response to a single event.
      schema:
        type: string
    start_time:
      name: start_time
      in: query
      description: 'Filters the webhook event notifications in the response to those created on or after this date and time and on or before the `end_time` value. Both values are in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6) format. Example: `start_time=2013-03-06T11:00:00Z`.'
      schema:
        type: string
  securitySchemes:
    Oauth2:
      type: oauth2
      description: Oauth 2.0 authentication
      flows:
        clientCredentials:
          tokenUrl: /v1/oauth2/token
          scopes:
            https://uri.paypal.com/services/subscriptions: Manage plan & subscription
externalDocs:
  url: https://developer.paypal.com/docs/api/subscriptions/v1/