Creating a webhook with Stripe for recurring donations and Auctions card requests

When you use Stripe as your payment processor, a webhook lets Stripe tell Soapbox Engage when something happens in your Stripe account. You need it to:

• Record the later payments of recurring donations in the Donations app. Each one is added to Donations > Transactions and, with Salesforce integration enabled, to Salesforce.
• Record subscriptions that are cancelled in Stripe.
• Save the card a bidder adds through a card request in the Auctions app. Without the webhook, the bidder's card never reaches Soapbox Engage, and the Auctions app will not send card requests.

Important: If you already have a Soapbox Engage webhook in Stripe, don't create a second one. Add the events it is missing instead.

To create the webhook:

1. Log in to Stripe.
2. Click Developers.
3. Click the Webhooks tab.

The next steps depend on your Stripe dashboard.

Option 1: Workbench is not enabled

Stripe shows the heading Webhook endpoints above a table, with an + Add endpoint button in the upper right of that table.

1. Click + Add endpoint.
2. For Endpoint URL, enter the address for your site's domain:
   • Standard domain: https://{myaccountprefix}.secure.nonprofitsoapbox.com/component/donations/transactionNotification, replacing {myaccountprefix} (without the curly brackets) with your Soapbox Engage account prefix.
   • Custom domain: https://{engage.example.org}/component/donations/transactionNotification, replacing {engage.example.org} (without the curly brackets) with your Soapbox Engage domain.
3. For Description, enter "Soapbox Engage endpoint".
4. For Listen to, select Events on your account.
5. Leave Version as it is.
6. For Select events to listen to, select these four events:
   • checkout.session.completed
   • customer.subscription.deleted
   • customer.subscription.updated
   • invoice.payment_succeeded
7. Click Add events.

Option 2: Workbench is enabled

Stripe shows no Webhook endpoints table, and a button labeled + Add destination.

1. Click + Add destination.
2. On the page titled Start by selecting which events you want to listen to, leave Your account selected.
3. Leave API version as Your current version.
4. For Events, select these four events:
   • checkout.session.completed
   • customer.subscription.deleted
   • customer.subscription.updated
   • invoice.payment_succeeded
5. Click Continue.
6. On the page titled Choose where you want to send events, leave Webhook endpoint selected.
7. Click Continue.
8. On the page titled Configure destinations, leave Destination Name as it is.
9. For Endpoint URL, enter the address for your site's domain:
   • Standard domain: https://{myaccountprefix}.secure.nonprofitsoapbox.com/component/donations/transactionNotification, replacing {myaccountprefix} (without the curly brackets) with your Soapbox Engage account prefix.
   • Custom domain: https://{engage.example.org}/component/donations/transactionNotification, replacing {engage.example.org} (without the curly brackets) with your Soapbox Engage domain.
10. For Description, enter "Soapbox Engage endpoint".
11. Click Create Destination.

Note: Use the domain you sign in to the administrator with. If your organization has a custom domain but you sign in to the administrator at your standard nonprofitsoapbox.com domain, use the standard domain. The Auctions app looks for the webhook on the domain you are signed in to, and reports that Stripe isn't set up if it can't find one there.

Once the webhook is in place:

• Later payments on existing and future recurring donations are added to Donations > Transactions with a Payment Occurrence of "Subsequent recurring."
• Subscriptions cancelled in Stripe are marked cancelled in Soapbox Engage.
• A card a bidder adds through an Auctions card request is saved as their card for that auction, and the Auctions app can send card requests.

Related articles:

• Updating an existing Stripe webhook for subscription cancellations and Auctions card requests
• Accepting recurring payments with Stripe in the Donations app
• Setting up credentials for Stripe in Soapbox