PayPal Webhooks API

openapi: 3.0.3
info:
  title: Paypal Subscriptions Authorizations Webhooks 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
  description: Use the `/webhooks` resource to subscribe your webhook listener to events, list webhooks for an app, show details for, update, delete, and list event subscriptions for webhooks.
paths:
  /v1/notifications/webhooks:
    post:
      summary: Paypal Create webhook
      description: Subscribes your webhook listener to events.
      operationId: webhooks.post
      responses:
        '201':
          description: A successful request returns the HTTP `201 Created` status code and a JSON response body with a [`webhook`](/docs/api/webhooks/v1/#definition-webhook) object that includes the webhook ID for later use.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook'
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhook'
            examples:
              webhook:
                value:
                  url: https://example.com/example_webhook
                  event_types:
                  - name: PAYMENT.AUTHORIZATION.CREATED
                  - name: PAYMENT.AUTHORIZATION.VOIDED
      security:
      - Oauth2:
        - https://uri.paypal.com/services/applications/webhooks
      tags:
      - Webhooks
    get:
      summary: Paypal List webhooks
      description: Lists webhooks for an app.
      operationId: webhooks.list
      responses:
        '200':
          description: A successful request returns the HTTP `200 OK` status code and a JSON response body that lists webhooks with webhook details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookList'
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      parameters:
      - $ref: '#/components/parameters/anchor_type'
      security:
      - Oauth2:
        - https://uri.paypal.com/services/applications/webhooks
      tags:
      - Webhooks
  /v1/notifications/webhooks/{webhook_id}:
    get:
      summary: Paypal Show webhook details
      description: Shows details for a webhook, by ID.
      operationId: webhooks.get
      responses:
        '200':
          description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows webhook details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook'
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      parameters:
      - $ref: '#/components/parameters/webhook_id'
      security:
      - Oauth2:
        - https://uri.paypal.com/services/applications/webhooks
      tags:
      - Webhooks
    patch:
      summary: Paypal Update webhook
      description: Updates a webhook to replace webhook fields with new values. Supports only the `replace` operation. Pass a `json_patch` object with `replace` operation and `path`, which is `/url` for a URL or `/event_types` for events. The `value` is either the URL or a list of events.
      operationId: webhooks.update
      responses:
        '200':
          description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows webhook details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook'
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      parameters:
      - $ref: '#/components/parameters/webhook_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/patch_request'
      security:
      - Oauth2:
        - https://uri.paypal.com/services/applications/webhooks
      tags:
      - Webhooks
    delete:
      summary: Paypal Delete webhook
      description: Deletes a webhook, by ID.
      operationId: webhooks.delete
      responses:
        '204':
          description: A successful request returns the HTTP `204 No Content` status code with no JSON response body.
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      parameters:
      - $ref: '#/components/parameters/webhook_id'
      security:
      - Oauth2:
        - https://uri.paypal.com/services/applications/webhooks
      tags:
      - Webhooks
  /v1/notifications/webhooks/{webhook_id}/event-types:
    get:
      summary: Paypal List event subscriptions for webhook
      description: Lists event subscriptions for a webhook, by ID.
      operationId: event-types.list
      responses:
        '200':
          description: A successful request returns the HTTP `200 OK` status code and a JSON response body that lists event subscriptions for a webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventTypeList'
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      parameters:
      - $ref: '#/components/parameters/webhook_id'
      security:
      - Oauth2:
        - https://uri.paypal.com/services/applications/webhooks
      tags:
      - Webhooks
components:
  schemas:
    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
    event_type:
      type: object
      title: Event Type
      description: An event type.
      properties:
        name:
          type: string
          description: The unique event name.<blockquote><strong>Note:</strong> To subscribe to all events, including events as they are added, specify an `*` as the value to represent a wildcard.</blockquote>
          readOnly: false
        description:
          type: string
          description: A human-readable description of the event.
          readOnly: true
        status:
          type: string
          description: The status of a webhook event.
          readOnly: true
        resource_versions:
          type: array
          description: 'Identifier for the event type example: 1.0/2.0 etc.'
          readOnly: true
          items:
            type: string
            description: The ID for an event type. For example, `1.0` or `2.0`.
      required:
      - name
    patch:
      type: object
      title: Patch
      description: The JSON patch object to apply partial updates to resources.
      properties:
        op:
          type: string
          description: The operation.
          enum:
          - add
          - remove
          - replace
          - move
          - copy
          - test
        path:
          type: string
          description: The <a href="https://tools.ietf.org/html/rfc6901">JSON Pointer</a> to the target document location at which to complete the operation.
        value:
          title: Patch Value
          description: The value to apply. The <code>remove</code> operation does not require a value.
        from:
          type: string
          description: The <a href="https://tools.ietf.org/html/rfc6901">JSON Pointer</a> to the target document location from which to move the value. Required for the <code>move</code> operation.
      required:
      - op
    EventTypeList:
      type: object
      title: Event Type List
      description: A list of webhook events.
      properties:
        event_types:
          type: array
          description: An array of webhook events.
          items:
            $ref: '#/components/schemas/event_type'
    webhook:
      type: object
      title: Webhook
      description: One or more webhook objects.
      properties:
        id:
          type: string
          description: The ID of the webhook.
          readOnly: true
        url:
          type: string
          format: uri
          description: The URL that is configured to listen on `localhost` for incoming `POST` notification messages that contain event information.
          readOnly: false
          maxLength: 2048
        event_types:
          type: array
          maxItems: 500
          description: An array of events to which to subscribe your webhook. To subscribe to all events, including events as they are added, specify the asterisk wild card. To replace the `event_types` array, specify the asterisk wild card. To list all supported events, <a href="#event-type_list">list available events</a>.
          readOnly: false
          items:
            $ref: '#/components/schemas/event_type'
        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:
      - url
      - event_types
    WebhookList:
      type: object
      title: Webhook List
      description: A list of webhooks.
      properties:
        webhooks:
          type: array
          description: An array of webhooks.
          items:
            $ref: '#/components/schemas/webhook'
    patch_request:
      type: array
      title: Patch Request
      description: An array of JSON patch objects to apply partial updates to resources.
      items:
        $ref: '#/components/schemas/patch'
    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:
    anchor_type:
      name: anchor_type
      in: query
      description: Filters the webhooks in the response by an `anchor_id` entity type.
      schema:
        type: string
        enum:
        - APPLICATION
        - ACCOUNT
        default: APPLICATION
    webhook_id:
      name: webhook_id
      in: path
      description: The ID of the webhook for which to list subscriptions.
      required: true
      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/