Webhooks API

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.

Webhooks (resource group)

Use the /webhooks resource to create, show details for, list all, update, and delete webhooks.

Create webhook

POST /v1/notifications/webhooks
Subscribes your webhook listener to events. A successful call returns a webhook object, which includes the webhook ID for later use.

Request

In the JSON request body, pass a webhook object with:

  • A list of events. An event can be a payment authorization, a payment state change, and so on.
  • The URL for your webhook listener. A webhook listener is a server that you configure at a specific web URL to listen for incoming HTTP POST notification messages that are triggered when those events occur. PayPal signs each notification message that it delivers to your web URL.
  • url

    string

    required

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

    Format: uri.

  • event_types

    array (contains the event_type object)

    required

    A list of events.
SDK samples: C#, Node.js, PHP, Python, Ruby

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/notifications/webhooks \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "url": "http://www.ebay.com/paypal_webhook",
  "event_types": [
  {
    "name": "PAYMENT.AUTHORIZATION.CREATED"
  },
  {
    "name": "PAYMENT.AUTHORIZATION.VOIDED"
  }
  ]
}'

Response

A successful call returns the HTTP 201 status code and a webhook object. This object includes the webhook ID for use in subsequent calls.

  • id

    string

    The ID of the webhook.

    Read only.

  • url

    string

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

    Format: uri.

  • event_types

    array (contains the event_type object)

    A list of events.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

{
  "id": "0EH40505U7160970P",
  "url": "http://www.ebay.com/paypal_webhook",
  "event_types": [
    {
      "name": "PAYMENT.AUTHORIZATION.CREATED",
      "description": "A payment authorization was created."
    },
    {
      "name": "PAYMENT.AUTHORIZATION.VOIDED",
      "description": "A payment authorization was voided."
    }
  ],
  "links": [
    {
      "href": "https://api.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
      "rel": "update",
      "method": "PATCH"
    },
    {
      "href": "https://api.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
      "rel": "delete",
      "method": "DELETE"
    }
  ]
}

Show webhook details

GET /v1/notifications/webhooks/webhook_id

Shows details for a webhook, by ID.

Parameters

Specify the webhook_id in the URI of a GET call.

  • webhook_id

    path string

    The ID of the webhook for which to show details.
SDK samples: PHP, Python, Ruby

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/notifications/webhooks/0EH40505U7160970P \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful call returns the HTTP 200 status code and a webhook object.

  • id

    string

    The ID of the webhook.

    Read only.

  • url

    string

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

    Format: uri.

  • event_types

    array (contains the event_type object)

    A list of events.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

{
  "id": "0EH40505U7160970P",
  "url": "http://www.ebay.com/paypal_webhook",
  "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"
    }
  ],
  "links": [
    {
      "href": "https://api.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
      "rel": "update",
      "method": "PATCH"
    },
    {
      "href": "https://api.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
      "rel": "delete",
      "method": "DELETE"
    }
  ]
}

List all webhooks

GET /v1/notifications/webhooks

Lists all webhooks.

Parameters

  • anchor_type

    query_string enum

    Filters the response by an entity type, anchor_id. Value is APPLICATION or ACCOUNT. Default is APPLICATION.

    Possible values: APPLICATION, ACCOUNT.

SDK samples: C#, Node.js, PHP, Python, Ruby

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/notifications/webhooks \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful call returns the HTTP 200 status code and a webhooks object.

  • webhooks

    array (contains the webhook object)

    One or more webhook objects.

Sample Response

{
  "webhooks": [
    {
      "id": "40Y916089Y8324740",
      "url": "http://www.ebay.com/paypal_webhook",
      "event_types": [
        {
          "name": "PAYMENT.AUTHORIZATION.CREATED",
          "description": "A payment authorization was created."
        },
        {
          "name": "PAYMENT.AUTHORIZATION.VOIDED",
          "description": "A payment authorization was voided."
        }
      ],
      "links": [
        {
          "href": "https://api.paypal.com/v1/notifications/webhooks/40Y916089Y8324740",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api.paypal.com/v1/notifications/webhooks/40Y916089Y8324740",
          "rel": "update",
          "method": "PATCH"
        },
        {
          "href": "https://api.paypal.com/v1/notifications/webhooks/40Y916089Y8324740",
          "rel": "delete",
          "method": "DELETE"
        }
      ]
    },
    {
      "id": "0EH40505U7160970P",
      "url": "http://www.ebay.com/another_paypal_webhook",
      "event_types": [
        {
          "name": "PAYMENT.AUTHORIZATION.CREATED",
          "description": "A payment authorization was created."
        },
        {
          "name": "PAYMENT.AUTHORIZATION.VOIDED",
          "description": "A payment authorization was voided."
        }
      ],
      "links": [
        {
          "href": "https://api.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
          "rel": "update",
          "method": "PATCH"
        },
        {
          "href": "https://api.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
          "rel": "delete",
          "method": "DELETE"
        }
      ]
    }
  ]
}

Update webhook

PATCH /v1/notifications/webhooks/webhook_id

Updates a webhook, by ID. Supports only the replace operation.

Parameters

Pass the webhook_id in the URI of a PATCH call.

  • webhook_id

    path string

    The ID of the webhook to update.

Request

  • items

    array (contains the json_patch object)

    A JSON patch object that you can use to apply partial updates to resources.
SDK samples: C#, Node.js, PHP, Python, Ruby

Sample Request

curl -v -X PATCH https://api.sandbox.paypal.com/v1/notifications/webhooks/0EH40505U7160970P \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '[
  {
  "op": "replace",
  "path": "/url",
  "value": "http://www.ebay.com/paypal_webhook_new_url"
  },
  {
  "op": "replace",
  "path": "/event_types",
  "value": [
    {
    "name": "PAYMENT.SALE.REFUNDED"
    }
  ]
  }
]'

Response

A successful call returns the HTTP 200 status code and a webhook object.

  • id

    string

    The ID of the webhook.

    Read only.

  • url

    string

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

    Format: uri.

  • event_types

    array (contains the event_type object)

    A list of events.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

{
  "id": "0EH40505U7160970P",
  "url": "http://www.ebay.com/paypal_webhook_new_url",
  "event_types": [
    {
      "name": "PAYMENT.SALE.REFUNDED",
      "description": "A sale payment was refunded."
    }
  ],
  "links": [
    {
      "href": "https://api.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
      "rel": "update",
      "method": "PATCH"
    },
    {
      "href": "https://api.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
      "rel": "delete",
      "method": "DELETE"
    }
  ]
}

Delete webhook

DELETE /v1/notifications/webhooks/webhook_id

Deletes a webhook, by ID.

Parameters

  • webhook_id

    path string

    The ID of the webhook to delete.
SDK samples: C#, Node.js, PHP, Python, Ruby

Sample Request

curl -v -X DELETE https://api.sandbox.paypal.com/v1/notifications/webhooks/5GP028458E2496506 \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful call returns the HTTP 204 No Content status code.

Sample Response

{
  "id": "0EH40505U7160970P",
  "url": "http://www.ebay.com/paypal_webhook",
  "event_types": [
    {
      "name": "PAYMENT.AUTHORIZATION.CREATED",
      "description": "A payment authorization was created."
    },
    {
      "name": "PAYMENT.AUTHORIZATION.VOIDED",
      "description": "A payment authorization was voided."
    }
  ],
  "links": [
    {
      "href": "https://api.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
      "rel": "update",
      "method": "PATCH"
    },
    {
      "href": "https://api.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
      "rel": "delete",
      "method": "DELETE"
    }
  ]
}

Webhook event notifications (resource group)

Use the /webhooks-events resource to show event notification details, list event notifications, and resend the notification for an event.

Show event notification details

GET /v1/notifications/webhooks-events/event_id

Shows details for an event notification, by ID.

Parameters

  • event_id

    path string

    The ID of the webhook event notification for which to show details.
SDK samples: Node.js, Python, Ruby

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/notifications/webhooks-events/8PT597110X687430LKGECATA \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful call returns the HTTP 200 status code and an event object.

  • id

    string

    The ID of the webhook event notification.

    Read only.

  • create_time

    string

    The date and time when the webhook event notification was created, in Internet date and time format.

    Read only.

    Format: date-time.

  • resource_type

    string

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

    Read only.

  • event_version

    string

    The version of the event.

    Read only.

  • event_type

    string

    The event that triggered the webhook event notification.

    Read only.

  • summary

    string

    A summary description for the event notification. For example, A payment authorization was created.

    Read only.

  • resource

    object

    The resource that triggered the webhook event notification.

    Read only.

  • status

    enum

    The event transmission status. Displayed only for internal API calls through the PayPal Developer portal.

    Read only.

    Possible values: SUCCESS('DELIVERED', 0), PENDING('FAIL_SOFT',1), FAILURE('FAIL_HARD',2).

  • transmissions

    array

    The list of transmissions for an event. Displayed only for internal API calls through the PayPal Developer portal.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2013-06-25T21:41:28Z",
  "resource_type": "authorization",
  "event_version": "1.0",
  "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.paypal.com/v1/payments/authorization/2DC87612EK520411B",
        "rel": "self",
        "method": "GET"
      },
      {
        "href": "https://api.paypal.com/v1/payments/authorization/2DC87612EK520411B/capture",
        "rel": "capture",
        "method": "POST"
      },
      {
        "href": "https://api.paypal.com/v1/payments/authorization/2DC87612EK520411B/void",
        "rel": "void",
        "method": "POST"
      },
      {
        "href": "https://api.paypal.com/v1/payments/payment/PAY-36246664YD343335CKHFA4AY",
        "rel": "parent_payment",
        "method": "GET"
      }
    ]
  },
  "links": [
    {
      "href": "https://api.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA/resend",
      "rel": "resend",
      "method": "POST"
    }
  ]
}

List event notifications

GET /v1/notifications/webhooks-events

Lists webhook event notifications. You can specify one or more optional query parameters to filter the response.

Parameters

To filter the response, include one or more optional query string parameters. You can specify a maximum date range of 45 days.

  • page_size

    query_string integer

    The number of webhook event notifications to return in the response.

    Default: 10.

  • start_time

    query_string 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 RFC 3339 Section 5.6 format. Example: start_time=2013-03-06T11:00:00Z.

    Format: date_time.

  • end_time

    query_string 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 RFC 3339 Section 5.6 format. Example: end_time=2013-03-06T11:00:00Z.

    Format: date_time.

  • transaction_id

    query_string string

    Filters the response to a single transaction, by ID.
  • event_type

    query_string string

    Filters the response to a single event.
SDK samples: C#, Node.js, PHP, Python, Ruby

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/notifications/webhooks-events \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful call returns the HTTP 200 status code and an event_list object.

  • events

    array (contains the event object)

    A webhook event notification.
  • count

    see description

    The number of items in each range of results. Note that the response might have fewer items than the requested page_size value.
    Possible types: integer
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

{
  "events": [
    {
      "id": "8PT597110X687430LKGECATA",
      "create_time": "2013-06-25T21:41:28Z",
      "resource_type": "authorization",
      "event_version": "1.0",
      "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.paypal.com/v1/payments/authorization/2DC87612EK520411B",
            "rel": "self",
            "method": "GET"
          },
          {
            "href": "https://api.paypal.com/v1/payments/authorization/2DC87612EK520411B/capture",
            "rel": "capture",
            "method": "POST"
          },
          {
            "href": "https://api.paypal.com/v1/payments/authorization/2DC87612EK520411B/void",
            "rel": "void",
            "method": "POST"
          },
          {
            "href": "https://api.paypal.com/v1/payments/payment/PAY-36246664YD343335CKHFA4AY",
            "rel": "parent_payment",
            "method": "GET"
          }
        ]
      },
      "links": [
        {
          "href": "https://api.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA/resend",
          "rel": "resend",
          "method": "POST"
        }
      ]
    },
    {
      "id": "HTSPGS710X687430LKGECATA",
      "create_time": "2013-06-25T21:41:28Z",
      "resource_type": "authorization",
      "event_version": "1.0",
      "event_type": "PAYMENT.AUTHORIZATION.CREATED",
      "summary": "A payment authorization was created",
      "resource": {
        "id": "HATH7S72EK520411B",
        "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-ALDSFJ64YD343335CKHFA4AY",
        "valid_until": "2013-07-24T21:39:15Z",
        "links": [
          {
            "href": "https://api.paypal.com/v1/payments/authorization/HATH7S72EK520411B",
            "rel": "self",
            "method": "GET"
          },
          {
            "href": "https://api.paypal.com/v1/payments/authorization/HATH7S72EK520411B/capture",
            "rel": "capture",
            "method": "POST"
          },
          {
            "href": "https://api.paypal.com/v1/payments/authorization/HATH7S72EK520411B/void",
            "rel": "void",
            "method": "POST"
          },
          {
            "href": "https://api.paypal.com/v1/payments/payment/PAY-HATH7S72EK520411B",
            "rel": "parent_payment",
            "method": "GET"
          }
        ]
      },
      "links": [
        {
          "href": "https://api.paypal.com/v1/notfications/webhooks-events/HTSPGS710X687430LKGECATA",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api.paypal.com/v1/notfications/webhooks-events/HTSPGS710X687430LKGECATA/resend",
          "rel": "resend",
          "method": "POST"
        }
      ]
    }
  ],
  "count": 2,
  "links": [
    {
      "href": "https://api.paypal.com/v1/notifications/webhooks-events/?start_time=2014-08-04T12:46:47-07:00&end_time=2014-09-18T12:46:47-07:00&page_size=2&move_to=next&index_time=2014-09-17T23:07:35Z&index_id=3",
      "rel": "next",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/v1/notifications/webhooks-events/?start_time=2014-08-04T12:46:47-07:00&end_time=2014-09-18T12:46:47-07:00&page_size=2&move_to=previous&index_time=2014-09-17T23:07:35Z&index_id=0",
      "rel": "previous",
      "method": "GET"
    }
  ]
}

Resend event notification

POST /v1/notifications/webhooks-events/event_id/resend

Resends an event notification, by event ID.

Parameters

  • event_id

    path string

    The ID of the webhook event notification to resend.

Request

  • webhook_ids

    array

    A list of webhook account IDs.
SDK samples: Node.js, Python, Ruby

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/notifications/webhooks-events/8PT597110X687430LKGECATA/resend \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "webhook_ids": [
  "12334456"
  ]
}'

Response

A successful call returns the HTTP 202 status code and an event object.

  • id

    string

    The ID of the webhook event notification.

    Read only.

  • create_time

    string

    The date and time when the webhook event notification was created, in Internet date and time format.

    Read only.

    Format: date-time.

  • resource_type

    string

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

    Read only.

  • event_version

    string

    The version of the event.

    Read only.

  • event_type

    string

    The event that triggered the webhook event notification.

    Read only.

  • summary

    string

    A summary description for the event notification. For example, A payment authorization was created.

    Read only.

  • resource

    object

    The resource that triggered the webhook event notification.

    Read only.

  • status

    enum

    The event transmission status. Displayed only for internal API calls through the PayPal Developer portal.

    Read only.

    Possible values: SUCCESS('DELIVERED', 0), PENDING('FAIL_SOFT',1), FAILURE('FAIL_HARD',2).

  • transmissions

    array

    The list of transmissions for an event. Displayed only for internal API calls through the PayPal Developer portal.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2013-06-25T21:41:28Z",
  "resource_type": "authorization",
  "event_version": "1.0",
  "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.paypal.com/v1/payments/authorization/2DC87612EK520411B",
        "rel": "self",
        "method": "GET"
      },
      {
        "href": "https://api.paypal.com/v1/payments/authorization/2DC87612EK520411B/capture",
        "rel": "capture",
        "method": "POST"
      },
      {
        "href": "https://api.paypal.com/v1/payments/authorization/2DC87612EK520411B/void",
        "rel": "void",
        "method": "POST"
      },
      {
        "href": "https://api.paypal.com/v1/payments/payment/PAY-36246664YD343335CKHFA4AY",
        "rel": "parent_payment",
        "method": "GET"
      }
    ]
  },
  "links": [
    {
      "href": "https://api.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA/resend",
      "rel": "resend",
      "method": "POST"
    }
  ]
}

Webhook events (resource group)

Use the /webhooks-event-types resource to list events to which webhooks can subscribe and the /webhooks/<webhook_id>/event-types resource to list event subscriptions for a webhook.

List available events

GET /v1/notifications/webhooks-event-types

Lists events to which an app can subscribe. For a list of webhook events, see webhook events.

Response

A successful call returns the HTTP 200 status code and an event_type_list object.

  • event_types

    array (contains the event_type object)

    A list of events.

Sample Response

{
  "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"
    },
    {
      "name": "PAYMENT.CAPTURE.REFUNDED",
      "description": "A capture payment was refunded.",
      "status": "ENABLED"
    },
    {
      "name": "PAYMENT.SALE.COMPLETED",
      "description": "A sale payment was completed.",
      "status": "ENABLED"
    },
    {
      "name": "PAYMENT.SALE.REFUNDED",
      "description": "A sale payment was refunded.",
      "status": "ENABLED"
    },
    {
      "name": "RISK.DISPUTE.CREATED",
      "description": "A dispute was filed against a transaction.",
      "status": "DEPRECATED"
    }
  ]
}

List event subscriptions for a webhook

GET /v1/notifications/webhooks/webhook_id/event-types

Lists the event subscriptions for a webhook, by ID.

Parameters

  • webhook_id

    path string

    The ID of the webhook for which to list subscriptions.
SDK samples: PHP, Python, Ruby

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/notifications/webhooks/0EH40505U7160970P/event-types \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful call returns the HTTP 200 status code and an event_type_list object.

  • event_types

    array (contains the event_type object)

    A list of events.

Sample Response

{
  "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"
    }
  ]
}

Simulate webhook event (resource group)

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.

Note: You can also use the Webhooks simulator to simulate webhook events.

Simulate webhook event

POST /v1/notifications/simulate-event

Simulates a webhook event. To simulate an event, you specify a sample payload in the request to send mock event data to the URL that you configured to listen for notification messages. The mock events serve to validate the connection to the listener URL and to show how webhook events look.

Note: You cannot verify webhook events that the simulator sends. You cannot resend an event notification or show webhook details for the mock event data.

Request

In the JSON request body, specify the URL that is configured to listen for notification messages and the event to simulate.

  • webhook_id

    string

    The ID of the webhook. If omitted, the URL is required.
  • url

    string

    The URL for the webhook endpoint. If omitted, the webhook ID is required.

    Format: uri.

  • event_type

    string

    required

    The event name. Specify one of the subscribed events. For each request, provide only one event.
SDK samples: Ruby

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/notifications/simulate-event \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "url": "http://www.ebay.com/paypal_webhook",
  "event_type": "PAYMENT.AUTHORIZATION.CREATED"
}'

Response

A successful call returns the HTTP 202 status code and an event object that contains static sample data.

  • id

    string

    The ID of the webhook event notification.

    Read only.

  • create_time

    string

    The date and time when the webhook event notification was created, in Internet date and time format.

    Read only.

    Format: date-time.

  • resource_type

    string

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

    Read only.

  • event_version

    string

    The version of the event.

    Read only.

  • event_type

    string

    The event that triggered the webhook event notification.

    Read only.

  • summary

    string

    A summary description for the event notification. For example, A payment authorization was created.

    Read only.

  • resource

    object

    The resource that triggered the webhook event notification.

    Read only.

  • status

    enum

    The event transmission status. Displayed only for internal API calls through the PayPal Developer portal.

    Read only.

    Possible values: SUCCESS('DELIVERED', 0), PENDING('FAIL_SOFT',1), FAILURE('FAIL_HARD',2).

  • transmissions

    array

    The list of transmissions for an event. Displayed only for internal API calls through the PayPal Developer portal.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2013-06-25T21:41:28Z",
  "resource_type": "authorization",
  "event_version": "1.0",
  "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.paypal.com/v1/payments/authorization/2DC87612EK520411B",
        "rel": "self",
        "method": "GET"
      },
      {
        "href": "https://api.paypal.com/v1/payments/authorization/2DC87612EK520411B/capture",
        "rel": "capture",
        "method": "POST"
      },
      {
        "href": "https://api.paypal.com/v1/payments/authorization/2DC87612EK520411B/void",
        "rel": "void",
        "method": "POST"
      },
      {
        "href": "https://api.paypal.com/v1/payments/payment/PAY-36246664YD343335CKHFA4AY",
        "rel": "parent_payment",
        "method": "GET"
      }
    ]
  },
  "links": [
    {
      "href": "https://api.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA/resend",
      "rel": "resend",
      "method": "POST"
    }
  ]
}

Verify webhook signature (resource group)

Use the /verify-webhook-signature resource to verify a webhook signature.

Verify webhook signature

POST /v1/notifications/verify-webhook-signature

Verifies a webhook signature.

Request

  • auth_algo

    string

    required

    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

    string

    required

    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.

    Format: uri.

  • transmission_id

    string

    required

    The ID of the HTTP transmission. Contained in the PAYPAL-TRANSMISSION-ID header of the notification message.
  • transmission_sig

    string

    required

    The PayPal-generated asymmetric signature. Contained in the PAYPAL-TRANSMISSION-SIG header of the notification message.
  • transmission_time

    string

    required

    The date and time of the HTTP transmission. Contained in the PAYPAL-TRANSMISSION-TIME header of the notification message.

    Format: date-time.

  • webhook_id

    string

    required

    The ID of the webhook as configured in your Developer Portal account.
  • webhook_event

    object

    required

    The webhook notification. Contained in the HTTP POST request body.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/notifications/verify-webhook-signature \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "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.paypal.com/v1/payments/authorization/2DC87612EK520411B",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/v1/payments/authorization/2DC87612EK520411B/capture",
      "rel": "capture",
      "method": "POST"
    },
    {
      "href": "https://api.paypal.com/v1/payments/authorization/2DC87612EK520411B/void",
      "rel": "void",
      "method": "POST"
    },
    {
      "href": "https://api.paypal.com/v1/payments/payment/PAY-36246664YD343335CKHFA4AY",
      "rel": "parent_payment",
      "method": "GET"
    }
    ]
  }
  }
}'

Response

  • verification_status

    enum

    The status of the signature verification.

    Possible values: SUCCESS, FAILURE.

Sample Response

{
  "verification_status": "FAILURE"
}

Common object definitions

abstract_status_report

  • transmission_id

    string

    The ID for the tranmission.
  • status

    object

    Common and re-usable definitions.
  • status_timestamp

    string

    The date and time when the status change occurred.

    Format: date-time.

  • classifiers

    object

    Tags for future retrieval.

classifiers

  • tags

    array

    An array of simple tags.
  • pairs

    object

    A set of regular JSON-style properties and values.

common_constructs

  • DeliveryStatus

    enum

    The enumerated list of possible delivery statuses.

    Possible values: SENT, DELIVERED, OPENED, FAIL_HARD, FAIL_SOFT, EXPIRED_BEFORE_DELIVERY.

error

  • id

    string

    The ID of the webhook error.

    Read only.

  • create_time

    string

    The date and time when the resource was created, in Internet date and time format.

    Read only.

    Format: date-time.

  • error_type

    string

    The error type that triggered the creation of this error.
  • client_id

    string

    The ID of the client for which this error occurred.
  • event_name

    string

    The name of the event that was being processed.
  • resource_identifier

    string

    The ID of the resource to POST to the webhooks endpoint.
  • resource_type

    string

    The resource type. For example, authorization, capture, notification, and so on.
  • resource

    object

    The most appropriate resource that is available in the context of the error.
  • resource_url

    string

    The URL from which to get the resource.

    Format: uri.

  • webhook_ids

    array

    The list of webhook IDs that were being posted when the error occurred.
  • debug_id

    string

    The correlation ID that triggered this error.
  • description

    string

    The detailed error description and a stack trace of the exception.
  • error_message

    string

    The error message that describes the error.
  • status

    enum

    The status of the error. Default is OPEN.

    Possible values: OPEN, RESOLVED.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

error_type

  • id

    string

    The ID for the webhook error type.

    Read only.

  • name

    string

    The unique error type name.
  • description

    string

    A human-readable description of the error type.

    Read only.

errorlist

  • items

    array (contains the error object)

    A webhook error.
  • total_count

    see description

    The number of items returned in each range of results. Note that the last results range might have fewer items than the requested number of items.
    Possible types: integer
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

errortypelist

  • error_types

    array (contains the error_type object)

    The type of webhook error that occurred.

event

  • id

    string

    The ID of the webhook event notification.

    Read only.

  • create_time

    string

    The date and time when the webhook event notification was created, in Internet date and time format.

    Read only.

    Format: date-time.

  • resource_type

    string

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

    Read only.

  • event_version

    string

    The version of the event.

    Read only.

  • event_type

    string

    The event that triggered the webhook event notification.

    Read only.

  • summary

    string

    A summary description for the event notification. For example, A payment authorization was created.

    Read only.

  • resource

    object

    The resource that triggered the webhook event notification.

    Read only.

  • status

    enum

    The event transmission status. Displayed only for internal API calls through the PayPal Developer portal.

    Read only.

    Possible values: SUCCESS('DELIVERED', 0), PENDING('FAIL_SOFT',1), FAILURE('FAIL_HARD',2).

  • transmissions

    array

    The list of transmissions for an event. Displayed only for internal API calls through the PayPal Developer portal.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

event_resend

  • webhook_ids

    array

    A list of webhook account IDs.

event_type

  • name

    string

    The unique event name.
  • description

    string

    A human-readable description of the event.

    Read only.

  • status

    string

    The status of a webhook event.

    Read only.

eventlist

  • events

    array (contains the event object)

    A webhook event notification.
  • count

    see description

    The number of items in each range of results. Note that the response might have fewer items than the requested page_size value.
    Possible types: integer
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

eventtypelist

  • event_types

    array (contains the event_type object)

    A list of events.

http_transmission_status_report

  • transmission_type

    enum

    The transmission type. Value is http.

    Possible values: http.

  • address

    string

    The target HTTP URL.
  • http_status

    see description

    The HTTP status code.
    Possible types: integer
  • reason_phrase

    string

    The HTTP reason string, if available.
  • response_headers

    object

    A set of HTTP headers, as a set of key-and-value pairs.
  • transmission_id

    string

    The ID for the tranmission.
  • status

    object

    Common and re-usable definitions.
  • status_timestamp

    string

    The date and time when the status change occurred.

    Format: date-time.

  • classifiers

    object

    Tags for future retrieval.

json_patch

  • op

    enum

    The operation to perform.

    Possible values: add, remove, replace, move, copy, test.

  • path

    string

    A JSON pointer that references a location in the target document where the operation is performed. A string value.
  • value

    see description

    The value to apply based on the operation. The remove operation does not require a value.
    Possible types: number, integer, string, boolean, null, array, object
  • from

    string

    A JSON pointer that references the location in the target document from which to move the value. A string value. Required for the move operation.

json_patch_request

  • items

    (contains the json_patch object)

    A JSON patch object that you can use to apply partial updates to resources.

publish_event_with_payload

  • anchor_type

    enum

    The type of webhook ID. Default is APPLICATION.

    Possible values: APPLICATION, ACCOUNT.

  • event_version

    string

    The version of the event.
  • event_type

    string

    The name of the event.
  • resource_type

    string

    The name of the resource in the resource element.
  • resource

    object

    The resource that is identified by the resource_type element.
  • summary

    string

    The publisher-provided event summary.
  • recipients

    array

    The list of recipients to which to send webhook notifications.
  • transaction_id

    string

    The ID of the PayPal transaction.
  • time_created

    string

    The date and time when the resource was created, in Internet date and time format.

    Format: date_time.

publish_event_with_reference

  • anchor_type

    enum

    The type of webhook ID. Default is APPLICATION.

    Possible values: APPLICATION, ACCOUNT.

  • event_version

    string

    The version of the event.
  • event_type

    string

    The name of the event.
  • resource_type

    string

    The name of the resource in the resource element.
  • resource_id

    string

    The ID for the resource to post to the webhook listener endpoint.
  • summary

    string

    The publisher-provided event summary.
  • recipients

    array

    The list of recipients to which to send webhook notifications.
  • transaction_id

    string

    The ID of the PayPal transaction.
  • time_created

    string

    The date and time when the resource was created in Internet date and time format.

    Format: date_time.

simulate_event

  • webhook_id

    string

    The ID of the webhook. If omitted, the URL is required.
  • url

    string

    The URL for the webhook endpoint. If omitted, the webhook ID is required.

    Format: uri.

  • event_type

    string

    The event name. Specify one of the subscribed events. For each request, provide only one event.

verify_webhook_signature

  • auth_algo

    string

    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

    string

    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.

    Format: uri.

  • transmission_id

    string

    The ID of the HTTP transmission. Contained in the PAYPAL-TRANSMISSION-ID header of the notification message.
  • transmission_sig

    string

    The PayPal-generated asymmetric signature. Contained in the PAYPAL-TRANSMISSION-SIG header of the notification message.
  • transmission_time

    string

    The date and time of the HTTP transmission. Contained in the PAYPAL-TRANSMISSION-TIME header of the notification message.

    Format: date-time.

  • webhook_id

    string

    The ID of the webhook as configured in your Developer Portal account.
  • webhook_event

    object

    The webhook notification. Contained in the HTTP POST request body.

verify_webhook_signature_response

  • verification_status

    enum

    The status of the signature verification.

    Possible values: SUCCESS, FAILURE.

webhook

  • id

    string

    The ID of the webhook.

    Read only.

  • url

    string

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

    Format: uri.

  • event_types

    array (contains the event_type object)

    A list of events.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

webhooklist

  • webhooks

    array (contains the webhook object)

    One or more webhook objects.

webhooklookuplist

  • webhooks_lookups

    array (contains the webhooks_lookup object)

    A webhooks lookup.

webhooks_lookup

  • id

    string

    The ID of the webhook lookup.

    Read only.

  • client_id

    string

    The application client ID.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Additional API information