Setting up Stripe webhooks

What the webhook does

A webhook lets Stripe push events to your site the moment they happen. Donor Merchant uses it to:

• Log recurring renewals - each subscription cycle is recorded as a new completed donation (this only happens via webhook).
• Mark refunds - a full refund in Stripe flips the WordPress record to refunded. A partial refund keeps the gift and records the amount returned.
• Record bank payments - ACH gifts clear days later, and the webhook records them when they do.
• Flag failed payments - declined gifts get marked failed, and when a recurring renewal is declined the donor is emailed a link to update their card.
• Record cancellations - a recurring gift cancelled in Stripe is marked cancelled in WordPress and leaves the donor portal.
• Catch closed-tab donations - if a donor pays but closes the tab before returning to your site, the webhook still completes the record and sends the receipt.

Set it up

1. In WordPress, open Donor Merchant → Settings → Payments and click Manage next to Stripe. The webhook field's description shows your exact endpoint URL. It looks like:

https://yoursite.org/wp-json/donor-merchant/v1/webhook/stripe

2. In the Stripe Dashboard, go to Developers → Webhooks → Add endpoint.
3. Paste the endpoint URL.
4. Select these six events:
   • payment_intent.succeeded
   • payment_intent.payment_failed
   • charge.refunded
   • invoice.paid
   • invoice.payment_failed
   • customer.subscription.deleted
5. Create the endpoint, then reveal its Signing secret (whsec_…).
6. Paste the signing secret into the Webhook signing secret field in Donor Merchant and save.

Verify it works

In the Stripe webhook page, use Send test event with payment_intent.succeeded - Stripe should report a 200 response. (The test event won't match a real donation, which is fine; a 200 means your endpoint received and verified it.)

Test mode vs live mode

Webhook endpoints are per-environment in Stripe. If you test with test keys, create the endpoint while the Stripe dashboard is in test mode; when you go live, create a second endpoint in live mode and update the signing secret in Donor Merchant.