Webhooks Management (1)

The PayPal REST APIs use webhooks for event notification. Webhooks are HTTP callbacks that receive notification messages for events. After you configure a webhook listener for your app, you can create a webhook, which subscribes the webhook listener for your app to events. The notifications namespace contains resource collections for webhooks.

Create webhook

post/v1/notifications/webhooks

Subscribes your webhook listener to events.

SecurityOauth2
Request
Request Body schema:
url
required
string <uri> <= 2048 characters

The URL that is configured to listen on localhost for incoming POST notification messages that contain event information.

required
Array of objects (Event Type) <= 500 items

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, list available events.

Responses
201

A successful request returns the HTTP 201 Created status code and a JSON response body with a webhook object that includes the webhook ID for later use.

Request samples
{}
Response samples
application/json
{}

List webhooks

get/v1/notifications/webhooks

Lists webhooks for an app.

SecurityOauth2
Request
query Parameters
anchor_type
string
Default: "APPLICATION"

Filters the webhooks in the response by an anchor_id entity type.

Enum: "APPLICATION" "ACCOUNT"
Request Body schema:
any
Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that lists webhooks with webhook details.

Request samples
{ }
Response samples
application/json
{}

Show webhook details

get/v1/notifications/webhooks/{webhook_id}

Shows details for a webhook, by ID.

SecurityOauth2
Request
path Parameters
webhook_id
required
string <= 50 characters ^[a-zA-Z0-9]+$

The ID of the webhook for which to show details.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows webhook details.

Request samples 
Response samples 
application/json
{}
Update webhook
patch/v1/notifications/webhooks/{webhook_id}
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.


SecurityOauth2 
Request 
path Parameters
webhook_id
required
string  <= 50 characters ^[a-zA-Z0-9]+$
The ID of the webhook to update.


 
Request Body schema: application/json
 Array 
op
required
string
The operation.


 Enum Value Description
add
Depending on the target location reference, completes one of these functions:
  • The target location is an array index. Inserts a new value into the array at the specified index.
  • The target location is an object parameter that does not already exist. Adds a new parameter to the object.
  • The target location is an object parameter that does exist. Replaces that parameter's value.
The value parameter defines the value to add. For more information, see 4.1. add.


remove
Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.


replace
Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.


move
Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.


copy
Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.


test
Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:
TypeConsidered equal if both values
stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
numbersAre numerically equal.
arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
For more information, see 4.6. test.


 
path
string
The JSON Pointer to the target document location at which to complete the operation.


 
value
object (Patch Value) 
The value to apply. The remove operation does not require a value.


 
from
string
The JSON Pointer to the target document location from which to move the value. Required for the move operation.


 
Responses 
200
A successful request returns the HTTP 200 OK status code and a JSON response body that shows webhook details.


Request samples 
application/json
[]
Response samples 
application/json
{}
Delete webhook
delete/v1/notifications/webhooks/{webhook_id}
Deletes a webhook, by ID.


SecurityOauth2 
Request 
path Parameters
webhook_id
required
string  <= 50 characters ^[a-zA-Z0-9]+$
The ID of the webhook to delete.


 
Responses 
204
A successful request returns the HTTP 204 No Content status code with no JSON response body.


Request samples 
Response samples 
application/json
{ }
List event subscriptions for webhook
get/v1/notifications/webhooks/{webhook_id}/event-types
Lists event subscriptions for a webhook, by ID.


SecurityOauth2 
Request 
path Parameters
webhook_id
required
string
The ID of the webhook for which to list subscriptions.


 
Responses 
200
A successful request returns the HTTP 200 OK status code and a JSON response body that lists event subscriptions for a webhook.


Request samples 
Response samples 
application/json
{
  • "event_types": [
    • {
      • "name": "PAYMENT.AUTHORIZATION.CREATED",
      • "description": "A payment authorization was created.",
      • "status": "ENABLED"
      },
    • {
      • "name": "PAYMENT.AUTHORIZATION.VOIDED",
      • "description": "A payment authorization was voided.",
      • "status": "ENABLED"
      },
    • {
      • "name": "RISK.DISPUTE.CREATED",
      • "description": "A dispute was filed against a transaction.",
      • "status": "DEPRECATED"
      }
    ]
}
Create webhook lookup
post/v1/notifications/webhooks-lookup
Creates a webhook lookup.


SecurityOauth2 
Request 
Request Body schema: 
any
 
Responses 
201
A successful request returns the HTTP 201 Created status code and a JSON response body that shows webhook lookup details.


Request samples 
{ }
Response samples 
application/json
{}
List webhook lookups
get/v1/notifications/webhooks-lookup
Lists webhook lookups.


SecurityOauth2 
Request 
Request Body schema: 
any
 
Responses 
200
A successful request returns the HTTP 200 OK status code and a JSON response body that lists webhook lookups with webhook lookup details.


Request samples 
{ }
Response samples 
application/json
{}
Show webhook lookup details
get/v1/notifications/webhooks-lookup/{webhook_lookup_id}
Shows details for a webhook lookup, by ID.


SecurityOauth2 
Request 
path Parameters
webhook_lookup_id
required
string
The ID of the webhook lookup for which to show details.


 
Responses 
200
A successful request returns the HTTP 200 OK status code and a JSON response body that shows webhook lookup details.


Request samples 
Response samples 
application/json
{}
Delete webhook lookup
delete/v1/notifications/webhooks-lookup/{webhook_lookup_id}
Deletes a webhook lookup, by ID.


SecurityOauth2 
Request 
path Parameters
webhook_lookup_id
required
string
The ID of the webhook lookup to delete.


 
Responses 
204
A successful request returns the HTTP 204 No Content status code with no JSON response body.


Request samples 
Response samples 
application/json
{ }
Verify webhook signature
post/v1/notifications/verify-webhook-signature
Verifies a webhook signature.


SecurityOauth2 
Request 
Request Body schema: 
auth_algo
required
string  <= 100 characters ^[a-zA-Z0-9]+$
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
required
string <uri>   <= 500 characters 
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
required
string  <= 50 characters ^(?!\d+$)\w+\S+
The ID of the HTTP transmission. Contained in the PAYPAL-TRANSMISSION-ID header of the notification message.


 
transmission_sig
required
string  <= 500 characters ^(?!\d+$)\w+\S+
The PayPal-generated asymmetric signature. Appears in the PAYPAL-TRANSMISSION-SIG header of the notification message.


 
transmission_time
required
string <date-time>   <= 100 characters 
The date and time of the HTTP transmission, in Internet date and time format. Appears in the PAYPAL-TRANSMISSION-TIME header of the notification message.


 
webhook_id
required
string  <= 50 characters ^[a-zA-Z0-9]+$
The ID of the webhook as configured in your Developer Portal account.


 
required
object (Event) 
A webhook event notification.


 
Responses 
200
A successful request returns the HTTP 200 OK status code and a JSON response body that shows the verification status.


Request samples 
{
  • "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": {}
}
Response samples 
application/json
{
  • "verification_status": "SUCCESS"
}
List available events
get/v1/notifications/webhooks-event-types
Lists available events to which any webhook can subscribe. For a list of supported events, see Webhook event names.


Responses 
200
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.


Response samples 
application/json
{
  • "event_types": [
    • {
      • "name": "PAYMENT.AUTHORIZATION.CREATED",
      • "description": "A payment authorization was created.",
      • "status": "ENABLED"
      },
    • {
      • "name": "PAYMENT.AUTHORIZATION.VOIDED",
      • "description": "A payment authorization was voided.",
      • "status": "ENABLED"
      },
    • {
      • "name": "PAYMENT.CAPTURE.COMPLETED",
      • "description": "A capture payment was completed.",
      • "status": "ENABLED"
      }
    ]
}
List event notifications
get/v1/notifications/webhooks-events
Lists webhooks event notifications. Use query parameters to filter the response.


SecurityOauth2 
Request 
query Parameters
page_size
integer
 Default:  10
The number of webhook event notifications to return in the response.


 
start_time
string
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 format. Example: start_time=2013-03-06T11:00:00Z.


 
end_time
string
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 format. Example: end_time=2013-03-06T11:00:00Z.


 
transaction_id
string
Filters the response to a single transaction, by ID.


 
event_type
string
Filters the response to a single event.


 
Responses 
200
A successful request returns the HTTP 200 OK status code and a JSON response body that lists webhooks event notifications.


Request samples 
Response samples 
application/json
{}
Show event notification details
get/v1/notifications/webhooks-events/{event_id}
Shows details for a webhooks event notification, by ID.


SecurityOauth2 
Request 
path Parameters
event_id
required
string  <= 50 characters ^[a-zA-Z0-9]+$
The ID of the webhook event notification for which to show details.


 
Responses 
200
A successful request returns the HTTP 200 OK status code and a JSON response body that shows webhooks event notification details.


Request samples 
Response samples 
application/json
{}
Resend event notification
post/v1/notifications/webhooks-events/{event_id}/resend
Resends a webhook event notification, by ID. Any pending notifications are not resent.


SecurityOauth2 
Request 
path Parameters
event_id
required
string  <= 50 characters ^[a-zA-Z0-9]+$
The ID of the webhook event notification to resend.


 
Request Body schema: 
webhook_ids
Array of strings  <= 500 items 
An array of webhook account IDs.


 
Responses 
202
A successful request returns the HTTP 202 Accepted status code and a JSON response body that shows webhook event notification details.


Request samples 
{
  • "webhook_ids": [
    • "12334456"
    ]
}
Response samples 
application/json
{}
Simulate webhook event
post/v1/notifications/simulate-event
Simulates a webhook event. In the JSON request body, specify a sample payload.
You need to subscribe to the following webhook events for Pay upon Invoice:
EventTrigger
PAYMENT.CAPTURE.COMPLETEDA payment capture completes.
PAYMENT.CAPTURE.DENIEDA payment capture is denied.
CHECKOUT.PAYMENT-APPROVAL.REVERSEDPayPal reverses a payment capture.


SecurityOauth2 
Request 
Request Body schema: 
webhook_id
string  <= 50 characters ^[a-zA-Z0-9]+$
The ID of the webhook. If omitted, the URL is required.


 
url
string <uri>   <= 2048 characters 
The URL for the webhook endpoint. If omitted, the webhook ID is required.


 
event_type
required
string  <= 50 characters ^[a-zA-Z0-9.]+$
The event name. Specify one of the subscribed events. For each request, provide only one event.


 
resource_version
string
The identifier for event type ex: 1.0/2.0 etc.


 
Responses 
202
A successful request returns the HTTP 202 Accepted status code and a JSON response body that shows details for the mock event.


Request samples 
{}
Response samples 
application/json
{}
Errors
INTERNAL_SERVER_ERROR
Message:
An internal server error has occurred.


Description: Resend the request at another time. If this error persists, contact PayPal Merchant Technical Support.




INVALID_RESOURCE_ID
Message:
Resource id is invalid.


Description: Provide a valid resource ID and resend the request.




INVALID_WEBHOOK_PATCH_REQUEST
Message:
The patch request is malformed.


Description: The patch request is malformed.




UNAUTHORIZED
Message:
Not authorized for this operation.


Description: You do not have the proper permissions to complete this request.




VALIDATION_ERROR
Message:
Invalid data provided.


Description: A validation error occurred with your request.




WEBHOOK_NUMBER_LIMIT_EXCEEDED
Message:
The webhook's number limit has exceeded.


Description: You can create a maximum of ten webhooks for an application. You have reached the maximum limit.




WEBHOOK_PATCH_REQUEST_NO_CHANGE
Message:
No change in webhook.


Description: The patch request to update webhooks has no change in request.




WEBHOOK_URL_ALREADY_EXISTS
Message:
Webhook URL already exists.


Description: A webhook already exists for the URL. Update the webhook or create a webhook with different URL.


Definitions
base_status_report
The common items for all status reports.


transmission_id
string
The ID for the tranmission.


 
status_timestamp
string <date-time> 
The date and time when the status changed, in Internet date and time format.


 
status
string (delivery_status) 
The delivery status.


 Enum: "SENT" "DELIVERED" "OPENED" "FAIL_HARD" "FAIL_SOFT" "EXPIRED_BEFORE_DELIVERY"  
object (classifiers) 
An array of tags and associated key-and-value pairs.


 
{
  • "transmission_id": "string",
  • "status_timestamp": "2019-08-24T14:15:22Z",
  • "status": "SENT",
  • "classifiers": {
    • "tags": [
      • "string"
      ],
    • "pairs": {
      • "property1": "string",
      • "property2": "string"
      }
    }
}
classifiers
An array of tags and associated key-and-value pairs.


tags
Array of strings
An array of tags.


 
object (Pairs) 
A set of one or more key-and-value pairs.


 
{
  • "tags": [
    • "string"
    ],
  • "pairs": {
    • "property1": "string",
    • "property2": "string"
    }
}
delivery_status
The delivery status.


string (delivery_status) 
The delivery status.


 Enum: "SENT" "DELIVERED" "OPENED" "FAIL_HARD" "FAIL_SOFT" "EXPIRED_BEFORE_DELIVERY"  
"SENT"
Destination
The destination that is intended for resend.


anchor_type
string  [ 1 .. 100 ] characters ^[A-Z0-9_]+$
 Default:  "APPLICATION"
This is an identifier for identifying, whether one intend to send an IPN or webhook.


 Enum Value Description
ACCOUNT
This identifier is used when one intend to send IPN.


APPLICATION
This identifier is used when one intend to send webhooks.


 
type
string  [ 1 .. 100 ] characters ^[A-Z0-9_]+$
 Default:  "ANCHOR_TYPE"
Destination type intended.


 Enum Value Description
PROVIDED
Destination type would be set to account level URL.


ORIGINAL
Destination type would be set only during resend.


ANCHOR_TYPE
Destination type would be set be for sending any IPN/Webhooks.


 
webhook_ids
Array of strings  [ 1 .. 10 ] items 
An array of webhook account IDs.


 
{
  • "anchor_type": "ACCOUNT",
  • "type": "PROVIDED",
  • "webhook_ids": [
    • "string"
    ]
}
Error
The error details.


name
required
string
The human-readable, unique name of the error.


 
message
required
string
The message that describes the error.


 
debug_id
required
string
The PayPal internal ID. Used for correlation purposes.


 
information_link
string
The information link, or URI, that shows detailed information about this error for the developer.


 
Array of objects (Error Details) 
An array of additional details about the error.


 
Array of objects (Link Description) 
An array of request-related HATEOAS links.


 
{
  • "name": "string",
  • "message": "string",
  • "debug_id": "string",
  • "information_link": "string",
  • "details": [
    • {
      • "field": "string",
      • "value": "string",
      • "location": "body",
      • "issue": "string",
      • "description": "string"
      }
    ],
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ]
}
Error Details
The error details. Required for client-side 4XX errors.


field
string
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
string
The value of the field that caused the error.


 
location
string
 Default:  "body"
The location of the field that caused the error. Value is body, path, or query.


 
issue
required
string
The unique, fine-grained application-level error code.


 
description
string
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.


 
{
  • "field": "string",
  • "value": "string",
  • "location": "body",
  • "issue": "string",
  • "description": "string"
}
error_type
The type of webhook error that occurred.


id
string
The ID for the webhook error type.


 
name
required
string
The unique error type name.


 
description
string
A human-readable description of the error type.


 
{
  • "id": "string",
  • "name": "string",
  • "description": "string"
}
Event
A webhook event notification.


id
string
The ID of the webhook event notification.


 
create_time
string <date-time> 
The date and time when the webhook event notification was created, in Internet date and time format.


 
resource_type
string
The name of the resource related to the webhook notification event.


 
event_version
string (Event Version) ^([0-9]+.[0-9]+)$
The event version in the webhook notification.


 
event_type
string
The event that triggered the webhook event notification.


 
summary
string
A summary description for the event notification.


 
resource_version
string (Resource Version) ^([0-9]+.[0-9]+)$
The resource version in the webhook notification.


 
object (Resource) 
The resource that triggered the webhook event notification.


 
Array of objects (Link Description) 
An array of request-related HATEOAS links.


 
{
  • "id": "string",
  • "create_time": "2019-08-24T14:15:22Z",
  • "resource_type": "string",
  • "event_version": "string",
  • "event_type": "string",
  • "summary": "string",
  • "resource_version": "string",
  • "resource": { },
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ]
}
Event Resend
Resends a webhook event notification, by ID.


webhook_ids
Array of strings  <= 500 items 
An array of webhook account IDs.


 
{
  • "webhook_ids": [
    • "string"
    ]
}
Event Type
An event type.


name
required
string
The unique event name.
Note: To subscribe to all events, including events as they are added, specify an * as the value to represent a wildcard.


 
description
string
A human-readable description of the event.


 
status
string
The status of a webhook event.


 
resource_versions
Array of strings
Identifier for the event type example: 1.0/2.0 etc.


 
{
  • "name": "string",
  • "description": "string",
  • "status": "string",
  • "resource_versions": [
    • "string"
    ]
}
Event Version
The event version in the webhook notification.


string (Event Version) ^([0-9]+.[0-9]+)$
The event version in the webhook notification.


 
"string"
event_list
A list of webhooks events.


Array of objects (Event) 
An array of webhooks events.


 
count
integer
The number of items in each range of results. Note that the response might have fewer items than the requested page_size value.


 
Array of objects (Link Description) 
An array of request-related HATEOAS links.


 
{
  • "events": [
    • {
      • "id": "string",
      • "create_time": "2019-08-24T14:15:22Z",
      • "resource_type": "string",
      • "event_version": "string",
      • "event_type": "string",
      • "summary": "string",
      • "resource_version": "string",
      • "resource": { },
      • "links": [
        • {
          • "href": "string",
          • "rel": "string",
          • "method": "GET"
          }
        ]
      }
    ],
  • "count": 0,
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ]
}
event_type_list
A list of webhook events.


Array of objects (Event Type) 
An array of webhook events.


 
{
  • "event_types": [
    • {
      • "name": "string",
      • "description": "string",
      • "status": "string",
      • "resource_versions": [
        • "string"
        ]
      }
    ]
}
Patch
The JSON patch object to apply partial updates to resources.


op
required
string
The operation.


 Enum Value Description
add
Depending on the target location reference, completes one of these functions:
  • The target location is an array index. Inserts a new value into the array at the specified index.
  • The target location is an object parameter that does not already exist. Adds a new parameter to the object.
  • The target location is an object parameter that does exist. Replaces that parameter's value.
The value parameter defines the value to add. For more information, see 4.1. add.


remove
Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.


replace
Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.


move
Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.


copy
Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.


test
Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:
TypeConsidered equal if both values
stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
numbersAre numerically equal.
arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
For more information, see 4.6. test.


 
path
string
The JSON Pointer to the target document location at which to complete the operation.


 
value
object (Patch Value) 
The value to apply. The remove operation does not require a value.


 
from
string
The JSON Pointer to the target document location from which to move the value. Required for the move operation.


 
{
  • "op": "add",
  • "path": "string",
  • "value": { },
  • "from": "string"
}
Patch Request
An array of JSON patch objects to apply partial updates to resources.


 Array 
op
required
string
The operation.


 Enum Value Description
add
Depending on the target location reference, completes one of these functions:
  • The target location is an array index. Inserts a new value into the array at the specified index.
  • The target location is an object parameter that does not already exist. Adds a new parameter to the object.
  • The target location is an object parameter that does exist. Replaces that parameter's value.
The value parameter defines the value to add. For more information, see 4.1. add.


remove
Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.


replace
Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.


move
Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.


copy
Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.


test
Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:
TypeConsidered equal if both values
stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
numbersAre numerically equal.
arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
For more information, see 4.6. test.


 
path
string
The JSON Pointer to the target document location at which to complete the operation.


 
value
object (Patch Value) 
The value to apply. The remove operation does not require a value.


 
from
string
The JSON Pointer to the target document location from which to move the value. Required for the move operation.


 
[
  • {
    • "op": "add",
    • "path": "string",
    • "value": { },
    • "from": "string"
    }
]
Resource Version
The resource version in the webhook notification.


string (Resource Version) ^([0-9]+.[0-9]+)$
The resource version in the webhook notification.


 
"string"
Simulate Event
Simulates a mock webhook event.


webhook_id
string  <= 50 characters ^[a-zA-Z0-9]+$
The ID of the webhook. If omitted, the URL is required.


 
url
string <uri>   <= 2048 characters 
The URL for the webhook endpoint. If omitted, the webhook ID is required.


 
event_type
required
string  <= 50 characters ^[a-zA-Z0-9.]+$
The event name. Specify one of the subscribed events. For each request, provide only one event.


 
resource_version
string
The identifier for event type ex: 1.0/2.0 etc.


 
{
  • "webhook_id": "string",
  • "url": "http://example.com",
  • "event_type": "string",
  • "resource_version": "string"
}
Verify Webhook Signature
A verify webhook signature request.


auth_algo
required
string  <= 100 characters ^[a-zA-Z0-9]+$
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
required
string <uri>   <= 500 characters 
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
required
string  <= 50 characters ^(?!\d+$)\w+\S+
The ID of the HTTP transmission. Contained in the PAYPAL-TRANSMISSION-ID header of the notification message.


 
transmission_sig
required
string  <= 500 characters ^(?!\d+$)\w+\S+
The PayPal-generated asymmetric signature. Appears in the PAYPAL-TRANSMISSION-SIG header of the notification message.


 
transmission_time
required
string <date-time>   <= 100 characters 
The date and time of the HTTP transmission, in Internet date and time format. Appears in the PAYPAL-TRANSMISSION-TIME header of the notification message.


 
webhook_id
required
string  <= 50 characters ^[a-zA-Z0-9]+$
The ID of the webhook as configured in your Developer Portal account.


 
required
object (Event) 
A webhook event notification.


 
{
  • "auth_algo": "string",
  • "cert_url": "http://example.com",
  • "transmission_id": "string",
  • "transmission_sig": "string",
  • "transmission_time": "2019-08-24T14:15:22Z",
  • "webhook_id": "string",
  • "webhook_event": {
    • "id": "string",
    • "create_time": "2019-08-24T14:15:22Z",
    • "resource_type": "string",
    • "event_version": "string",
    • "event_type": "string",
    • "summary": "string",
    • "resource_version": "string",
    • "resource": { },
    • "links": [
      • {
        • "href": "string",
        • "rel": "string",
        • "method": "GET"
        }
      ]
    }
}
Verify Webhook Signature Response
The verify webhook signature response.


verification_status
required
string
The status of the signature verification.


 Enum: "SUCCESS" "FAILURE"  
{
  • "verification_status": "SUCCESS"
}
Webhook
One or more webhook objects.


id
string
The ID of the webhook.


 
url
required
string <uri>   <= 2048 characters 
The URL that is configured to listen on localhost for incoming POST notification messages that contain event information.


 
required
Array of objects (Event Type)   <= 500 items 
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, list available events.


 
Array of objects (Link Description) 
An array of request-related HATEOAS links.


 
{
  • "id": "string",
  • "url": "http://example.com",
  • "event_types": [
    • {
      • "name": "string",
      • "description": "string",
      • "status": "string",
      • "resource_versions": [
        • "string"
        ]
      }
    ],
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ]
}
Webhook Lookup
The webhook lookup details.


id
string
The ID of the webhook lookup.


 
client_id
string  <= 128 characters ^(?!\d+$)\w+\S+
The application client ID.


 
Array of objects (Link Description) 
An array of request-related HATEOAS links.


 
{
  • "id": "string",
  • "client_id": "string",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ]
}
Webhook Lookup List
A list of webhook lookups.


Array of objects (Webhook Lookup) 
An array of webhook lookups.


 
{
  • "webhooks_lookups": [
    • {
      • "id": "string",
      • "client_id": "string",
      • "links": [
        • {
          • "href": "string",
          • "rel": "string",
          • "method": "GET"
          }
        ]
      }
    ]
}
webhook_list
A list of webhooks.


Array of objects (Webhook) 
An array of webhooks.


 
{
  • "webhooks": [
    • {
      • "id": "string",
      • "url": "http://example.com",
      • "event_types": [
        • {
          • "name": "string",
          • "description": "string",
          • "status": "string",
          • "resource_versions": [
            • "string"
            ]
          }
        ],
      • "links": [
        • {
          • "href": "string",
          • "rel": "string",
          • "method": "GET"
          }
        ]
      }
    ]
}