PayPal Notification Webhooks API
The PayPal Notification Webhooks API lets developers subscribe to and manage webhook event notifications for payments, refunds, disputes, and other PayPal account activity.
OpenAPI Specification
openapi: 3.0.3
info:
title: Paypal Webhooks Management
description: The PayPal REST APIs use <a href="/docs/api/notifications/webhooks/"/>webhooks</a> for event notification. Webhooks are HTTP callbacks that receive notification messages for events. After you configure a webhook listener for your app, you can <a href="#webhooks_create">create a webhook</a>, which subscribes the webhook listener for your app to events. The <code>notifications</code> namespace contains resource collections for webhooks.
version: '1.11'
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: Simulate-Event
description: Use the `/simulate-event` resource to use a sample payload to simulate a webhook event. The events that this call generates only serve to validate the connection to the listener URL and to show how webhook events look. <blockquote><strong>Note:</strong> You can also use the <a href="/docs/api/notifications/webhooks/simulator/">Webhooks simulator</a> to simulate webhook events.</blockquote>
- name: Verify-Webhook-Signature
description: Use the `/verify-webhook-signature` resource to verify a webhook signature.
- 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.
- name: Webhooks-Event-Types
description: Use the `/webhooks-event-types` resource to list available events to which any webhook can subscribe.
- name: Webhooks-Events
description: Use the `/webhooks-events` resource to list, show details for, and resend event notifications.
- name: Webhooks-Lookup
description: Use the `/webhooks-lookup` resource to create, list, show details for, and delete webhook lookups.
externalDocs:
url: https://developer.paypal.com/docs/api/webhooks/v1/
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
"/v1/notifications/webhooks-lookup":
post:
summary: Paypal Create webhook lookup
description: Creates a webhook lookup.
operationId: webhooks-lookup.post
responses:
'201':
description: A successful request returns the HTTP `201 Created` status code and a JSON response body that shows webhook lookup details.
content:
application/json:
schema:
"$ref": "#/components/schemas/webhooks_lookup"
default:
description: The error response.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
security:
- Oauth2:
- https://uri.paypal.com/services/applications/webhooks
tags:
- Webhooks-Lookup
get:
summary: Paypal List webhook lookups
description: Lists webhook lookups.
operationId: webhooks-lookup.list
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code and a JSON response body that lists webhook lookups with webhook lookup details.
content:
application/json:
schema:
"$ref": "#/components/schemas/WebhookLookupList"
default:
description: The error response.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
security:
- Oauth2:
- https://uri.paypal.com/services/applications/webhooks
tags:
- Webhooks-Lookup
"/v1/notifications/webhooks-lookup/{webhook_lookup_id}":
get:
summary: Paypal Show webhook lookup details
description: Shows details for a webhook lookup, by ID.
operationId: webhooks-lookup.get
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows webhook lookup details.
content:
application/json:
schema:
"$ref": "#/components/schemas/webhooks_lookup"
default:
description: The error response.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
parameters:
- "$ref": "#/components/parameters/webhook_lookup_id"
security:
- Oauth2:
- https://uri.paypal.com/services/applications/webhooks
tags:
- Webhooks-Lookup
delete:
summary: Paypal Delete webhook lookup
description: Deletes a webhook lookup, by ID.
operationId: webhooks-lookup.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_lookup_id"
security:
- Oauth2:
- https://uri.paypal.com/services/applications/webhooks
tags:
- Webhooks-Lookup
"/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
"/v1/notifications/webhooks-event-types":
get:
summary: Paypal List available events
description: Lists available events to which any webhook can subscribe. For a list of supported events, see [Webhook event names](/docs/api/notifications/webhooks/event-names/).
operationId: webhooks-event-types.list
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code and a JSON response body that lists available events to which any webhook can subscribe.
content:
application/json:
schema:
"$ref": "#/components/schemas/EventTypeList"
default:
description: The error response.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
tags:
- Webhooks-Event-Types
"/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
"/v1/notifications/simulate-event":
post:
summary: Paypal Simulate webhook event
description: Simulates a webhook event. In the JSON request body, specify a sample payload.<br>You need to subscribe to the following webhook events for Pay upon Invoice:<br><table><thead><tr><th>Event</th><th>Trigger</th></tr></thead><tbody><tr><td><code>PAYMENT.CAPTURE.COMPLETED</code></td><td>A payment capture completes.</td></tr><tr><td><code>PAYMENT.CAPTURE.DENIED</code></td><td>A payment capture is denied.</td></tr><tr><td><code>CHECKOUT.PAYMENT-APPROVAL.REVERSED</code></td><td>PayPal reverses a payment capture.</td></tr></tbody></table>
operationId: simulate-event.post
responses:
'202':
description: A successful request returns the HTTP `202 Accepted` status code and a JSON response body that shows details for the mock event.
content:
application/json:
schema:
"$ref": "#/components/schemas/event"
default:
description: The error response.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/simulate_event"
examples:
simulate_event:
value:
url: https://example.com/example_webhook
event_type: PAYMENT.AUTHORIZATION.CREATED
resource_version: '1.0'
security:
- Oauth2:
- https://uri.paypal.com/services/applications/webhooks
tags:
- Simulate-Event
components:
securitySchemes:
Oauth2:
type: oauth2
description: Oauth 2.0 authentication
flows:
clientCredentials:
tokenUrl: "/v1/oauth2/token"
scopes:
https://uri.paypal.com/services/applications/webhooks: Access/update Webhooks.
https://uri.paypal.com/services/applications/verify-webhook-signature: Verify Webhook Signature
schemas:
error_details:
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:
"$ref": "#/components/schemas/error_location"
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
error_location:
type: string
description: The location of the field that caused the error. Value is `body`, `path`, or `query`.
enum:
- body
- path
- query
default: body
error_link_description:
title: Link Description
description: The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information.
type: object
required:
- href
- rel
properties:
href:
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.
type: string
minLength: 0
maxLength: 20000
pattern: "^.*$"
rel:
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).
type: string
minLength: 0
maxLength: 100
pattern: "^.*$"
method:
description: The HTTP method required to make the related call.
type: string
minLength: 3
maxLength: 6
pattern: "^[A-Z]*$"
enum:
- GET
- POST
- PUT
- DELETE
- PATCH
error_400:
type: object
title: Bad Request Error
description: Request is not well-formed, syntactically incorrect, or violates schema.
properties:
name:
type: string
enum:
- INVALID_REQUEST
message:
type: string
enum:
- Request is not well-formed, syntactically incorrect, or violates schema.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_401:
type: object
title: Unauthorized Error
description: Authentication failed due to missing Authorization header, or invalid authentication credentials.
properties:
name:
type: string
enum:
- AUTHENTICATION_FAILURE
message:
type: string
enum:
- Authentication failed due to missing authorization header, or invalid authentication credentials.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_403:
type: object
title: Not Authorized Error
description: 'The client is not authorized to access this resource, although it may have valid credentials. '
properties:
name:
type: string
enum:
- NOT_AUTHORIZED
message:
type: string
enum:
- Authorization failed due to insufficient permissions.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_404:
type: object
title: Not found Error
description: The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available.
properties:
name:
type: string
enum:
- RESOURCE_NOT_FOUND
message:
type: string
enum:
- The specified resource does not exist.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_409:
type: object
title: Resource Conflict Error
description: The server has detected a conflict while processing this request.
properties:
name:
type: string
enum:
- RESOURCE_CONFLICT
message:
type: string
enum:
- The server has detected a conflict while processing this request.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_415:
type: object
title: Unsupported Media Type Error
description: The server does not support the request payload's media type.
properties:
name:
type: string
enum:
- UNSUPPORTED_MEDIA_TYPE
message:
type: string
enum:
- The server does not support the request payload's media type.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_422:
type: object
title: Unprocessable Entity Error
description: The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 response in that there are no systemic problems limiting the API from performing the request.
properties:
name:
type: string
enum:
- UNPROCESSABLE_ENTITY
message:
type: string
enum:
- The requested action could not be performed, semantically incorrect, or failed business validation.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_500:
type: object
title: Internal Server Error
description: This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server.
properties:
name:
type: string
enum:
- INTERNAL_SERVER_ERROR
message:
type: string
enum:
- An internal server error occurred.
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
example:
name: INTERNAL_SERVER_ERROR
message: An internal server error occurred.
debug_id: 90957fca61718
links:
- href: https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR
rel: information_link
error_503:
type: object
title: Service Unavailable Error
description: The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime.
properties:
name:
type: string
enum:
- SERVICE_UNAVAILABLE
message:
type: string
enum:
- Service Unavailable.
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
example:
name: SERVICE_UNAVAILABLE
message: Service Unavailable.
debug_id: 90957fca61718
information_link: https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE
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"
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"
EventList:
type: object
title: Event List
description: A list of webhooks events.
properties:
events:
type: array
description: An array of webhooks
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paypal/refs/heads/main/openapi/paypal-notification-webhooks-openapi-original.yml