Webhook notifications

The PayPal REST APIs use webhooks for event notification.

Note: The NVP/SOAP APIs use the IPN message service for event notification.

Overview

Webhooks are HTTP callbacks that receive notification messages for events.

As a merchant, you can configure a webhook listener and subscribe it to events. A webhook listener is a server that listens at a specific URL for incoming HTTP POST notification messages that are triggered when events occur. PayPal signs each notification message that it delivers to your webhook listener.

After you create a listener, you can use a sample payload to simulate a webhook event to verify that your listener can successfully receive event data without any connectivity issues. After you verify your listener, subscribe it to a list of events. Finally, monitor the notifications that your listener receives when events occur.

To complete these tasks, you can use the PayPal dashboards or the Webhooks API.

Webhooks are asynchronous, their order is not guaranteed, and idempotency might lead to a duplicate notification of the same event type.

Next, learn how to configure your listener to receive notification messages for events.

Create webhooks for notification

To configure your webhook listener to receive notification messages for payment state changes and other events:
1. Required Meet the prerequisites.
2. Required Configure a webhook listener.
3. Optional Simulate webhook events.
4. Required Subscribe your webhook listener to events.
5. Optional Monitor event notifications.

Prerequisites

Before you can use the Webhooks API, you must make your first call and learn about REST API authentication and headers. If you are a non-US developer, see International Developer Questions.

Configure a webhook listener

As an example, you can use the PayPal Node SDK to configure a webhook listener. After you configure a listener, note the URL for the listener. You'll need this URL to simulate webhook events and subscribe your webhook listener to events.

Next, simulate webhook events to verify that you have configured your webhook URL correctly.

Simulate webhook events

You can use a sample payload to simulate a webhook event. By using the simulator, you can verify that the URL you have configured to accept webhook notification messages can successfully receive event data without any connectivity issues.

To simulate a webhook event, use either:

Next, subscribe your listener to events.

Subscribe your webhook listener to events

When you subscribe your listener to events, you define:

  • A list of events, such as a payment authorization, payment state change, and so on.
  • The URL for your webhook listener.

To subscribe your webhook listener to events, use either:

Next, monitor event notifications.

Monitor event notifications

You can monitor webhook event notifications that your listener receives when events occur.

To monitor notifications, use either:

Next, learn about the content of notification messages.

Notification messages

When an event occurs, PayPal issues an HTTP POST notification message to your app at the webhook listener URL that you defined in your webhook.

Because anyone can theoretically POST an HTTPS payload to your app, PayPal signs notification messages and sends them over HTTPS (SSL/TLS) to your apps. Event headers for notification messages contain the PayPal-generated asymmetric signature and information that you can use to validate the signature.

The JSON-formatted POST notification message contains event information. If your app is unavailable or takes too long to respond, PayPal cancels the call and tries to resend the notification message 25 times over the course of three days.

The resource_type and event_type parameters in the notification message indicate which event triggered the notification message:

{
  "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.sandbox.paypal.com/v1/payments/authorization/2DC87612EK520411B",
        "rel":"self",
        "method":"GET"
      },
      {
        "href":"https://api.sandbox.paypal.com/v1/payments/authorization/2DC87612EK520411B/capture",
        "rel":"capture",
        "method":"POST"
      },
      {
        "href":"https://api.sandbox.paypal.com/v1/payments/authorization/2DC87612EK520411B/void",
        "rel":"void",
        "method":"POST"
      },
      {
        "href":"https://api.sandbox.paypal.com/v1/payments/payment/PAY-36246664YD343335CKHFA4AY",
        "rel":"parent_payment",
        "method":"GET"
      }
    ]
  },
  "links":[
    {
      "href":"https://api.sandbox.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA",
      "rel":"self",
      "method":"GET"
    },
    {
      "href":"https://api.sandbox.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA/resend",
      "rel":"resend",
      "method":"POST"
    }
  ]
}

To get the latest resource from PayPal, navigate to the HATEOAS self link from the received payload.

Your app must verify that notification messages originated from PayPal, were not altered or corrupted during transmission, were targeted for you, and contain a valid signature. To validate the signature, use the information in event headers.

When your app receives the notification message, it must respond with a HTTP 200-level status code. If your app responds with any other status code, PayPal tries to resend the notification message 25 times over the course of three days.

Event headers

Event headers for notification messages contain the PayPal-generated asymmetric signature and information that you can use to validate the signature:

Event header Description
PAYPAL-TRANSMISSION-SIG The PayPal-generated asymmetric signature.
PAYPAL-AUTH-ALGO The algorithm that PayPal used to generate the signature and that you can use to verify the signature.
PAYPAL-CERT-URL The X509 public key certificate.
Download the certificate from this URL and use it to verify the signature.

To generate the signature, PayPal concatenates and separates these items with the pipe (|) character. To validate a signature, use this input string:

transmissionId|timeStamp|webhookId|crc32

The fields in the string are:

Field Description
transmissionId The unique ID of the HTTP transmission.
Contained in PAYPAL-TRANSMISSION-ID header of the notification message.
timeStamp The date and time when the HTTP message was transmitted.
Contained in PAYPAL-TRANSMISSION-TIME header of the notification message.
webhookId The ID of the webhook resource for the destination URL to which PayPal delivers the event notification.
crc32 The Cyclic Redundancy Check (CRC32) checksum for the body of the HTTP payload.

Note: When you validate the signature for notification messages that the Webhooks simulator generates, the webhook ID might vary depending on which method you used to simulate the event:

  • If you used a webhook ID, use that same ID to validate the event.
  • If you used a webhook URL, use WEBHOOK_ID to validate the event.

The authentication algorithm specified in PAYPAL-AUTH-ALGO uses an asymmetric signature algorithm, such as RSA with SHA256. This enables PayPal to use a private key to create the signature in PAYPAL-TRANSMISSION-SIG and enables you to use a public key defined in PAYPAL-CERT-URL to verify the webhook.

This Java pseudo code combines all headers and the input string to perform the verification:

String inputString = String.format("%s|%s|%s|%s", transmissionId, timeStamp, webhookId, crc32(eventBody));
// Get the signatureAlgorithm from the PAYPAL-AUTH-ALGO HTTP header
Signature signatureAlgorithm = Signature.getInstance("signatureAlgorithm");
// Get the certData from the URL provided in the HTTP headers and cache it
Certificate certificate = X509Certificate.getInstance(certData);
signatureAlgorithm.initVerify(certificate.getPublicKey());
signatureAlgorithm.update(inputString.getBytes());
// Actual signature is base 64 encoded and available in the HTTP headers
byte[] actualSignature = Base64.decodeBase64(actualSignatureEncoded.getBytes());
boolean isValid = signatureAlgorithm.verify(actualSignature);

Additional information