Configure Webhooks

Webhooks are HTTP callbacks that receive notification messages for events. To create a webhook at PayPal, users 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 configure a listener, you can use a sample payload to simulate a webhook event. When you simulate an event, the simulator validates that your listener can successfully receive event data without any connectivity issues and generates mock event data to show you how webhook events look. You cannot verify these mock events.

After you validate your listener, you can subscribe your listener to events. When you subscribe your listener to events, you define:

A list of events

An event can be a payment authorization, a payment state change, and so on. To determine to which events to subscribe, review the supported webhook event names.

Your webhook listener URL

A webhook listener is a server that you configure at a specific web URL to listen for incoming HTTP POSTnotification messages that are triggered when those events occur. PayPal signs each notification message that it delivers to your web URL.

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

Note: Webhooks will be sent only after the seller has completed all steps to receive payments. Each country may have the seller complete a series of tasks in order to complete the setup process. If any of the steps are missing, the webhook will not be sent.

Integration steps

To configure your webhook listener to receive notification messages for payment state changes and other events:

Set up your development environment

Before you can integrate Webhooks, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get Started.

Then, return to this page to integrate Webhooks.

Configure a webhook listener

A webhook listener is a server that listens at a specific URL for incoming HTTP POST notification messages that are triggered when events occur.
After you configure a listener, note the URL for the listener.

Validate your listener configuration with mock webhook events

After you configure a listener, you can use a sample payload to simulate a webhook event. When you simulate an event, the simulator:

Validates that your listener can successfully receive event data without any connectivity issues.

Generates mock event data to show you how webhook events look.

Note: The simulator generates mock events for demonstration purposes. You can view these events to see how events look. However, because these are mock events:

You cannot verify the simulator-generated events.

You cannot resend an event notification for a simulator-generated event.

You cannot show webhook details for a simulator-generated event.

After the simulator queues one or more mock events, your webhook listener URL can listen for HTTP POST notification messages. Each test event appears in your logs in the order that your listener receives them. The simulator sends mock static event data and event headers, which contain the PayPal-generated asymmetric signature and information that you can use to validate the signature.

Verify event notifications

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

Note: You cannot verify the mock simulator-generated events.

When you verify events, you can list webhook events by app. You can filter this list by date range, resource, and event type. You can also show status and details for an event and resend an event notification.

Webhooks events for the PayPal Commerce Platform

When you send a transaction to PayPal for a seller who has not completed their account setup, the status of the transaction is set to pending. PayPal sends a PAYMENT.CAPTURE.PENDING webhook with the reason code seller_setup_pending.

Once the seller has completed PayPal account setup, PayPal sends these webhooks:

PAYMENT.CAPTURE.COMPLETED to indicate that the payment capture has changed from pending to completed.

MERCHANT.ONBOARDING.COMPLETED to indicate that the seller has completed account setup. You can subscribe to webhooks to be alerted when a seller's account setup is complete.

PayPal also sends the MERCHANT.PARTNER-CONSENT.REVOKED webhook when the seller account is closed, or the account setup consents have been revoked.

PayPal sends the CHECKOUT.ORDER.APPROVED when the buyer has approved the payment on PayPal.

Important: To get the highest conversion rates for alternative payment methods, listen to the CHECKOUT.ORDER.APPROVED webhook and then capture the order.