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 — refund in Stripe, and the WordPress record flips to refunded.
• Flag failed payments — declined gifts get marked failed.
• 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. 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 exactly these four events:
   • payment_intent.succeeded
   • payment_intent.payment_failed
   • charge.refunded
   • invoice.paid
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.