Back to help center

Webhooks

Gratora uses incoming webhooks to receive real-time notifications from payment gateways. When a payment event occurs on Stripe or PayPal, the gateway sends a webhook to your site so Gratora can update donation records automatically.

How incoming webhooks work

Each gateway has a dedicated webhook endpoint on your site:

POST /wp-json/gratora/v1/webhooks/{gateway}

For the two online gateways, those endpoints are:

POST /wp-json/gratora/v1/webhooks/stripe
POST /wp-json/gratora/v1/webhooks/paypal

When Stripe or PayPal processes a payment, refund, or subscription change, it sends an HTTP POST request to the matching URL. Gratora verifies the request signature, identifies the event type, and updates your donation data accordingly.

The Offline and Sandbox gateways take no webhooks. Nothing sent to their endpoints is processed.

Webhook signature verification

Every incoming webhook is verified before Gratora acts on it, so a request that did not genuinely come from the gateway, or that was tampered with in transit, changes nothing.

The two gateways verify differently. Stripe deliveries are checked on your own server against the webhook signing secret you saved. PayPal deliveries are checked by calling PayPal back and asking it to verify the transmission headers against the webhook id you saved, so with no webhook id there is nothing to verify against and every delivery is refused.

When verification fails, Gratora records the delivery as Not verified and does nothing else. Stripe deliveries get a 401 and PayPal deliveries get a 400, shown against the delivery in the gateway’s own dashboard.

Stripe webhook events

Gratora listens for Stripe webhook events related to payments and subscriptions. When you save your Stripe keys in the Gratora gateway settings, Gratora registers this endpoint on your Stripe account for you and stores its signing secret. On a local site Stripe cannot reach the endpoint, so nothing is registered: create the webhook yourself in the Stripe dashboard and paste its signing secret into the Stripe card in Gratora’s gateway settings.

Common events Gratora handles include:

  • Payment completions and failures
  • Subscription renewals and cancellations
  • Refund processing
  • Disputes, both when the funds are withdrawn and when they are reinstated

PayPal webhook events

Gratora does not create the PayPal webhook for you. Copy the webhook endpoint from the PayPal card in Gratora’s gateway settings, add it as a webhook in your PayPal app, subscribe it to the payment and subscription events, then paste the webhook id back into the same credentials section. Sandbox and live are separate PayPal apps, so each mode has its own webhook and its own id.

Until a webhook id is saved for the mode you are in, PayPal is offered for one-time donations only. It is not offered as an option on a recurring donation at all. PayPal charges the first payment the moment the donor approves a subscription, and the opening sale webhook is the only thing that records that payment, so a recurring donation taken with no webhook id would be charged and never booked.

Gratora acts on these events:

  • PAYMENT.CAPTURE.COMPLETED confirms a one-time donation
  • PAYMENT.CAPTURE.PENDING moves a one-time donation PayPal is holding to Processing
  • PAYMENT.CAPTURE.DENIED and PAYMENT.CAPTURE.DECLINED mark a one-time donation failed
  • PAYMENT.CAPTURE.REFUNDED records a refund made in the PayPal dashboard against a one-time donation
  • BILLING.SUBSCRIPTION.ACTIVATED marks the recurring plan active
  • BILLING.SUBSCRIPTION.CANCELLED and BILLING.SUBSCRIPTION.EXPIRED end the plan, and email the donor when the end started at PayPal rather than in Gratora
  • BILLING.SUBSCRIPTION.SUSPENDED marks the plan past due, unless the donor paused or skipped it themselves
  • BILLING.SUBSCRIPTION.UPDATED applies an amount or schedule change the donor approved at PayPal
  • PAYMENT.SALE.COMPLETED records the opening payment on a new subscription, and every renewal after it
  • PAYMENT.SALE.DENIED and BILLING.SUBSCRIPTION.PAYMENT.FAILED count a declined renewal against the plan and email the donor

Any other event type is logged and ignored.

One thing Stripe does is not covered on PayPal. Refunds, reversals and disputes are handled for one-time donations only, so a refunded or disputed recurring payment does not update Gratora.

Webhook log

Gratora records every incoming webhook delivery under Fundraising > Tools > Logs, alongside the failures it records for itself. A gateway resends until it gets a 2xx, and every attempt is recorded, so the log shows how many attempts an event took rather than only the last of them. Each entry records:

  • Source: which gateway sent the delivery, webhook.stripe or webhook.paypal
  • What it says: the type of event (for example, payment_intent.succeeded or PAYMENT.CAPTURE.COMPLETED), with any error message underneath it
  • Outcome: Processed, No action needed, Not verified, or Handling failed
  • When: when the request arrived

Filter the list by source, or narrow it to problems only. Clear log empties it, and is offered to users who can manage WordPress options.

Log retention

The newest 2,000 deliveries are kept, and older ones are dropped as new ones arrive. You do not need to clean up the log manually.

Troubleshooting failed webhooks

If donations are not updating after payment, start at the gateway’s own delivery list. In Stripe, that is your dashboard under Developers > Webhooks. In PayPal, open the webhook you added to your REST app at developer.paypal.com.

Signature verification failures

Symptoms: Stripe reports 401 responses, or PayPal reports 400 responses, and donations do not update after payment.

Likely cause: For Stripe, the webhook signing secret is wrong or outdated. For PayPal, the webhook id is missing, or it belongs to a different webhook or a different app.

Solution: For Stripe, verify that the webhook signing secret in the Gratora gateway settings matches the one in your Stripe dashboard. For PayPal, verify that the webhook id in the PayPal card is the id of the webhook on the app whose credentials you saved. Test and live are stored separately, so each mode needs its own signing secret or webhook id.

PayPal offers no recurring option

Symptoms: Your form offers recurring donations, but PayPal is missing from the payment options when a donor picks a recurring amount.

Likely cause: No PayPal webhook id is saved for the mode you are in.

Solution: Add the webhook in your PayPal app and paste its id into the PayPal card in the Payment gateways tab. Sandbox and live have separate ids, so saving one does not cover the other. PayPal returns to the recurring options once the id is saved.

Webhooks not arriving

Symptoms: The gateway records no deliveries at all, or every attempt fails to connect.

Likely cause: Your site is not reachable from the internet, or a firewall is blocking incoming POST requests.

Solution:

  1. Confirm your site has a valid SSL certificate and is publicly accessible.
  2. Check that your server or hosting firewall allows POST requests to /wp-json/gratora/v1/webhooks/stripe and /wp-json/gratora/v1/webhooks/paypal.
  3. Review the webhook delivery logs in your gateway’s dashboard for HTTP errors.

Events not handled

Symptoms: The gateway reports a successful delivery, a 200 response, but nothing changes in Gratora.

Likely cause: The event type is not one that Gratora processes, or the related donation record was not found. The delivery is still logged either way.

Solution: Find the delivery under Fundraising > Tools > Logs and read its outcome. An event type Gratora does not act on reads “No action needed.” A delivery whose donation could not be found reads “Handling failed,” with the reason underneath it, and the thing to check then is that the donation exists in your Gratora records. The response Gratora returned to the gateway says the same, so you can read it in the gateway’s dashboard instead.

PayPal retries the first subscription payment

Symptoms: PayPal shows a 503 response for a PAYMENT.SALE.COMPLETED delivery, and a later attempt at the same event succeeds.

Likely cause: The sale arrived before the subscription was recorded on your site, so there was nothing to book the payment against yet.

Solution: None needed. Gratora answers 503 on purpose so that PayPal redelivers, and the retry records the payment once the plan is on file.