PayPal Verify-Webhook-Signature API

openapi: 3.0.3
info:
  title: Paypal Subscriptions Authorizations Verify-Webhook-Signature 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: Verify-Webhook-Signature
  description: Use the `/verify-webhook-signature` resource to verify a webhook signature.
paths:
  /v1/notifications/verify-webhook-signature:
    post:
      summary: Paypal Verify webhook signature
      description: Verifies a webhook signature.
      operationId: verify-webhook-signature.post
      responses:
        '200':
          description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows the verification status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/verify_webhook_signature_response'
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/verify_webhook_signature'
            examples:
              verify_webhook_signature:
                value:
                  transmission_id: 69cd13f0-d67a-11e5-baa3-778b53f4ae55
                  transmission_time: '2016-02-18T20:01:35Z'
                  cert_url: cert_url
                  auth_algo: SHA256withRSA
                  transmission_sig: lmI95Jx3Y9nhR5SJWlHVIWpg4AgFk7n9bCHSRxbrd8A9zrhdu2rMyFrmz+Zjh3s3boXB07VXCXUZy/UFzUlnGJn0wDugt7FlSvdKeIJenLRemUxYCPVoEZzg9VFNqOa48gMkvF+XTpxBeUx/kWy6B5cp7GkT2+pOowfRK7OaynuxUoKW3JcMWw272VKjLTtTAShncla7tGF+55rxyt2KNZIIqxNMJ48RDZheGU5w1npu9dZHnPgTXB9iomeVRoD8O/jhRpnKsGrDschyNdkeh81BJJMH4Ctc6lnCCquoP/GzCzz33MMsNdid7vL/NIWaCsekQpW26FpWPi/tfj8nLA==
                  webhook_id: 1JE4291016473214C
                  webhook_event:
                    id: 8PT597110X687430LKGECATA
                    create_time: '2013-06-25T21:41:28Z'
                    resource_type: authorization
                    event_type: PAYMENT.AUTHORIZATION.CREATED
                    summary: A payment authorization was created
                    resource:
                      id: 2DC87612EK520411B
                      create_time: '2013-06-25T21:39:15Z'
                      update_time: '2013-06-25T21:39:17Z'
                      state: authorized
                      amount:
                        total: '7.47'
                        currency: USD
                        details:
                          subtotal: '7.47'
                      parent_payment: PAY-36246664YD343335CKHFA4AY
                      valid_until: '2013-07-24T21:39:15Z'
                      links:
                      - href: https://api-m.paypal.com/v1/payments/authorization/2DC87612EK520411B
                        rel: self
                        method: GET
                      - href: https://api-m.paypal.com/v1/payments/authorization/2DC87612EK520411B/capture
                        rel: capture
                        method: POST
                      - href: https://api-m.paypal.com/v1/payments/authorization/2DC87612EK520411B/void
                        rel: void
                        method: POST
                      - href: https://api-m.paypal.com/v1/payments/payment/PAY-36246664YD343335CKHFA4AY
                        rel: parent_payment
                        method: GET
      security:
      - Oauth2:
        - https://uri.paypal.com/services/applications/webhooks
        - https://uri.paypal.com/services/applications/verify-webhook-signature
      tags:
      - Verify-Webhook-Signature
components:
  schemas:
    verify_webhook_signature:
      type: object
      title: Verify Webhook Signature
      description: A verify webhook signature request.
      properties:
        auth_algo:
          type: string
          maxLength: 100
          pattern: ^[a-zA-Z0-9]+$
          description: The algorithm that PayPal uses to generate the signature and that you can use to verify the signature. Extract this value from the `PAYPAL-AUTH-ALGO` response header, which is received with the webhook notification.
        cert_url:
          type: string
          maxLength: 500
          format: uri
          description: The X.509 public key certificate. Download the certificate from this URL and use it to verify the signature. Extract this value from the `PAYPAL-CERT-URL` response header, which is received with the webhook notification.
        transmission_id:
          type: string
          maxLength: 50
          pattern: ^(?!\d+$)\w+\S+
          description: The ID of the HTTP transmission. Contained in the `PAYPAL-TRANSMISSION-ID` header of the notification message.
        transmission_sig:
          type: string
          maxLength: 500
          pattern: ^(?!\d+$)\w+\S+
          description: The PayPal-generated asymmetric signature. Appears in the `PAYPAL-TRANSMISSION-SIG` header of the notification message.
        transmission_time:
          type: string
          maxLength: 100
          format: date-time
          description: The date and time of the HTTP transmission, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Appears in the `PAYPAL-TRANSMISSION-TIME` header of the notification message.
        webhook_id:
          type: string
          maxLength: 50
          pattern: ^[a-zA-Z0-9]+$
          description: The ID of the webhook as configured in your Developer Portal account.
        webhook_event:
          $ref: '#/components/schemas/event'
      required:
      - auth_algo
      - cert_url
      - transmission_id
      - transmission_sig
      - transmission_time
      - webhook_id
      - webhook_event
    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
    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]+)$
    verify_webhook_signature_response:
      type: object
      title: Verify Webhook Signature Response
      description: The verify webhook signature response.
      properties:
        verification_status:
          type: string
          description: The status of the signature verification.
          enum:
          - SUCCESS
          - FAILURE
      required:
      - verification_status
    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
  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/