Observation-mode PayPal

Choose the lightest PayPal setup that works.

Start with exports, add webhook-only monitoring without a PayPal client secret, then use full sync only when you want historical backfill. It does not issue refunds, cancel subscriptions, submit dispute evidence, or mutate PayPal records.

Open PayPal settingsOpen PayPal appsPayPal webhook docs

On this page

PayPal setup guide

Jump straight to the part you need, then return to PayPal settings when you are ready to save the webhook ID.

Setup modesWebhook stepsEvent listTroubleshooting

PayPal setup ladder

No client secretNo-secret uploadUpload PayPal transaction, subscription, or dispute exports for a one-time Ghost Audit.
No client secretWebhook-only monitoringCreate a Revenue Linter webhook URL and save the PayPal webhook ID. Revenue Linter verifies signatures locally.
AdvancedFull historical syncConnect a PayPal REST app only when you want API backfill for subscriptions, transactions, and disputes.

Webhook-only setup sequence

  1. Create or open your PayPal REST app.

    Use Sandbox first. Move to Live after a clean webhook event and Revenue Pulse run.

  2. Create a webhook-only endpoint in Revenue Linter.

    Dashboard > Settings > PayPal setup can create a webhook URL without a PayPal client secret.

  3. Copy the Revenue Linter webhook URL.

    Revenue Linter shows one webhook URL per PayPal connection. It looks like:

    https://revenuelinter.com/api/webhooks/paypal/<connectionId>
  4. Create a webhook in PayPal.

    In your PayPal REST app, add the Revenue Linter webhook URL and subscribe to the recommended event types below.

  5. Copy the PayPal webhook ID.

    PayPal returns a webhook ID after webhook creation. Save that ID back in Revenue Linter.

  6. Run Revenue Pulse.

    Webhook-only mode monitors future events. Use full sync only if you also want historical backfill.

  7. Confirm webhook diagnostics.

    After PayPal sends a sandbox event, open Dashboard > Settings > Webhook diagnostics, refresh events, and process queued events.

  8. Send PayPal IDs in app-state snapshots.

    Include paypalPayerId and paypalSubscriptionId where available so Revenue Linter can compare PayPal state against product access.

Recommended PayPal events

Use exact event subscriptions for the beta. Exact events keep the Revenue Linter queue cleaner than subscribing to every event type.

BILLING.SUBSCRIPTION.CREATEDBILLING.SUBSCRIPTION.ACTIVATEDBILLING.SUBSCRIPTION.UPDATEDBILLING.SUBSCRIPTION.CANCELLEDBILLING.SUBSCRIPTION.SUSPENDEDBILLING.SUBSCRIPTION.EXPIREDBILLING.SUBSCRIPTION.PAYMENT.FAILEDPAYMENT.SALE.COMPLETEDPAYMENT.SALE.REFUNDEDPAYMENT.SALE.REVERSEDPAYMENT.CAPTURE.COMPLETEDPAYMENT.CAPTURE.REFUNDEDPAYMENT.CAPTURE.REVERSEDCUSTOMER.DISPUTE.CREATEDCUSTOMER.DISPUTE.UPDATEDCUSTOMER.DISPUTE.RESOLVED

What Revenue Linter does with PayPal webhooks

Subscriptions

Mirrors subscription lifecycle events so Revenue Pulse can detect PayPal free riders and zombie subscribers.

Payments, refunds, reversals

Mirrors sale and capture events for reconciliation, refund parity, and active-access checks.

Disputes

Mirrors dispute events so Evidence Readiness can flag missing terms, login, usage, cancellation, refund, or support evidence.

Troubleshooting

  • Webhook returns 404: the PayPal connection is missing a saved webhook ID, or the connection ID in the URL is wrong.
  • Webhook returns 400: the PayPal signature headers are missing, the certificate URL is unsafe, the raw-body signature check failed, or the transmission is stale.
  • No findings after webhook setup: process queued webhook events, send app-state snapshots with PayPal IDs, then run Revenue Pulse.
  • Sandbox works but Live does not: confirm the webhook was created on the Live app and the Live endpoint was created in Revenue Linter.