Overview
When setting up PayPal (Modern) within Payments2Us, the webhook is the mechanism that allows PayPal to send payment notifications and updates (e.g. successful payments, refunds, and recurring renewals) directly into Salesforce.
In most cases, only one PayPal webhook setup is required per environment (sandbox or production).
Once configured, it automatically handles payment events for all Payment Forms linked to the same Merchant Facility.
💡 General Rule
✅ Only one PayPal webhook is needed per Salesforce environment.
This is because PayPal automatically retries failed notifications (2–3 times) and Payments2Us validates each transaction using the unique billing token/ txn ref to locate and update the correct recurring payment record.
This means that even if you have several forms or recurring payment records across your org, a single webhook can handle all PayPal notifications - as long as it’s set up correctly on a form linked to the live Merchant Facility.
The following are different scenarios situatinos and what todo using the above general rule for webhooks:
Scenario 1 – Multiple Payment Forms under one Merchant Facility
If your organisation uses multiple Payment Forms (e.g. different campaigns, donations, or events) under the same Merchant Facility, you only need to set up the PayPal webhook on one of them.
Payments2Us processes all PayPal events through the Merchant Facility level - once connected, all related Payment Forms under that facility receive updates through the same webhook.
✅ Best Practice:
Configure the webhook on one primary Payment Form (for example, the one used for recurring donations).
Ensure that no other Payment Form under the same Merchant Facility has the webhook secret key configured.
Keep sandbox and live setups separate (see Scenario 4).
Scenario 2 – The Primary Payment Form Uses Another Gateway (e.g. Stripe or Shopify)
If your main Payment Form is already used for another gateway’s webhook:
Choose another Payment Form linked to the same Merchant Facility.
Configure the PayPal webhook on that alternate form.
💡 The webhook doesn’t have to be on the public-facing or most-used form - any form under the same Merchant Facility will work.
Scenario 3 – Previously Configured Webhook on Another Form
If a webhook was previously configured on another Payment Form:
Open that Payment Form record in Salesforce.
Remove the PayPal Webhook Secret Key.
Keep the webhook configured only on the current active Payment Form.
⚠️ Multiple webhook configurations under the same Merchant Facility may cause duplicate event notifications or payment update failures.
Scenario 4 – Sandbox vs Live Environments
Each environment must have its own webhook setup:
| Environment | Configuration |
|---|---|
| Sandbox (Test) | Sandbox PayPal account → Sandbox Merchant Facility → Test Payment Form |
| Live (Production) | Live PayPal account → Live Merchant Facility → Live Payment Form |
🚫 Do not reuse webhook URLs across sandbox and production.
Each must point to its own.salesforce-sites.comdomain for correct event routing.
Scenario 5 – Multiple Merchant Facilities in Use
If you manage multiple Merchant Facilities (e.g. separate entities, business units, or currencies), setup considerations depend on how your PayPal accounts are structured.
⚙️ Summary:
Using one PayPal account across multiple facilities works.
If Different Paypal accounts then each Merchant Facility does not need it's own PayPal webhook setup.
Scenario 6 – Recurring Payments Not Updating
If recurring payments fail to update or appear missing:
Verify that the webhook is configured on the Payment Form linked to the Merchant Facility handling the recurring payments.
Check that the webhook license is assigned on that Merchant Facility.
Ensure that all required PayPal event types are selected.
Confirm only one active webhook per Merchant Facility.
🧩 Because PayPal retries notifications automatically and Payments2Us matches them using the billing token (starting with “i-”), missing updates usually indicate a configuration issue - not a timing or delivery failure.
Summary Table
| ✅ Do | ❌ Don’t |
|---|---|
| Configure one PayPal webhook per Merchant Facility | Set up multiple webhooks on forms in the same Merchant Facility |
| Keep test and live webhooks separate | Use the same URL for both environments |
| Remove outdated or duplicate webhook secret keys | Leave old entries active |
| Ensure all required event types are selected | Miss critical events like Payment sale completed
|
| Assign webhook license to Merchant Facility | Skip license configuration |