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: application/json
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
application/json
{}
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"
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 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/notifications/webhooks \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ECvJ_yBNz_UfMmCvWEbT_2ZWXdzbFFQZ-1Y5K2NGgeHn'
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 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/notifications/webhooks/0EH40505U7160970P \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ECvJ_yBNz_UfMmCvWEbT_2ZWXdzbFFQZ-1Y5K2NGgeHn'
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: 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 
curl -v -X DELETE https://api-m.sandbox.paypal.com/v1/notifications/webhooks/5GP028458E2496506 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ECvJ_yBNz_UfMmCvWEbT_2ZWXdzbFFQZ-1Y5K2NGgeHn'

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 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/notifications/webhooks/0EH40505U7160970P/event-types \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ECvJ_yBNz_UfMmCvWEbT_2ZWXdzbFFQZ-1Y5K2NGgeHn'
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
Responses
201

A successful request returns the HTTP 201 Created status code and a JSON response body that shows webhook lookup details.

Request samples 
curl -v -X POST https://api-m.sandbox.paypal.com/v1/notifications/webhooks-lookup \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ECvJ_yBNz_UfMmCvWEbT_2ZWXdzbFFQZ-1Y5K2NGgeHn'
Response samples
application/json
{}

List webhook lookups

get/v1/notifications/webhooks-lookup

Lists webhook lookups.

SecurityOauth2
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 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/notifications/webhooks-lookup \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ECvJ_yBNz_UfMmCvWEbT_2ZWXdzbFFQZ-1Y5K2NGgeHn'
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 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/notifications/webhooks-lookup \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ECvJ_yBNz_UfMmCvWEbT_2ZWXdzbFFQZ-1Y5K2NGgeHn'
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 
curl -v -X DELETE https://api-m.sandbox.paypal.com/v1/notifications/webhooks-lookup \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ECvJ_yBNz_UfMmCvWEbT_2ZWXdzbFFQZ-1Y5K2NGgeHn'

Verify webhook signature

post/v1/notifications/verify-webhook-signature

Verifies a webhook signature.

SecurityOauth2
Request
Request Body schema: application/json
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
application/json
{
  • "auth_algo": "SHA256withRSA",
  • "cert_url": "cert_url",
  • "transmission_id": "69cd13f0-d67a-11e5-baa3-778b53f4ae55",
  • "transmission_sig": "lmI95Jx3Y9nhR5SJWlHVIWpg4AgFk7n9bCHSRxbrd8A9zrhdu2rMyFrmz+Zjh3s3boXB07VXCXUZy/UFzUlnGJn0wDugt7FlSvdKeIJenLRemUxYCPVoEZzg9VFNqOa48gMkvF+XTpxBeUx/kWy6B5cp7GkT2+pOowfRK7OaynuxUoKW3JcMWw272VKjLTtTAShncla7tGF+55rxyt2KNZIIqxNMJ48RDZheGU5w1npu9dZHnPgTXB9iomeVRoD8O/jhRpnKsGrDschyNdkeh81BJJMH4Ctc6lnCCquoP/GzCzz33MMsNdid7vL/NIWaCsekQpW26FpWPi/tfj8nLA==",
  • "transmission_time": "2016-02-18T20:01:35Z",
  • "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.

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/notifications/webhooks-event-types \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ECvJ_yBNz_UfMmCvWEbT_2ZWXdzbFFQZ-1Y5K2NGgeHn'
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 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events-transmissions \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ECvJ_yBNz_UfMmCvWEbT_2ZWXdzbFFQZ-1Y5K2NGgeHn'
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 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/8PT597110X687430LKGECATA \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ECvJ_yBNz_UfMmCvWEbT_2ZWXdzbFFQZ-1Y5K2NGgeHn'
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: application/json
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
application/json
{
  • "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: application/json
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
application/json
{}
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: 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: 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: 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: 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"
          }
        ]
      }
    ]
}