Skip to main content

Webhooks Reference

Webhooks are essential for PaywallWP Pro to function correctly. They allow payment gateways to notify your site about subscription events in real-time.

Setup Instructions

For step-by-step webhook setup, see the tutorials:

Why Webhooks Are Required​

Without webhooks:

  • ❌ Subscriptions won't activate after payment
  • ❌ Recurring payments won't update status
  • ❌ Cancellations won't sync
  • ❌ Refunds won't be reflected
  • ❌ Failed payments won't be handled

With webhooks:

  • ✅ Instant subscription activation
  • ✅ Automatic renewal processing
  • ✅ Real-time cancellation sync
  • ✅ Automatic refund handling
  • ✅ Failed payment notifications

Webhook Endpoints​

GatewayEndpoint URL
Stripehttps://yoursite.com/wp-json/paywallwp/v1/stripe-webhook
PayPalhttps://yoursite.com/wp-json/paywallwp/v1/paypal-webhook

Replace yoursite.com with your actual domain.

HTTPS Required

Webhook URLs must use HTTPS. Payment gateways will reject HTTP endpoints.

Required Events​

Stripe Events​

EventPurpose
checkout.session.completedInitial subscription payment completed
customer.subscription.createdNew subscription created
customer.subscription.updatedPlan changes, renewals, status updates
customer.subscription.deletedSubscription canceled or ended
invoice.paidSuccessful renewal payment
invoice.payment_failedFailed renewal payment
charge.refundedRefund processed

PayPal Events​

EventPurpose
BILLING.SUBSCRIPTION.ACTIVATEDNew subscription started
BILLING.SUBSCRIPTION.CANCELLEDSubscription canceled
BILLING.SUBSCRIPTION.EXPIREDSubscription period ended
BILLING.SUBSCRIPTION.SUSPENDEDPayment failed, subscription paused
PAYMENT.SALE.COMPLETEDPayment received
PAYMENT.SALE.REFUNDEDRefund processed

Test vs Live Webhooks​

You need separate webhooks for each environment:

EnvironmentStripePayPal
Test/SandboxCreate in Test modeCreate in Sandbox app
Live/ProductionCreate in Live modeCreate in Live app
Don't Reuse Webhooks

Each environment has different API keys and webhook secrets. Always create new webhooks when switching between test and live modes.

Verifying Webhook Setup​

Stripe​

  1. Go to Stripe Webhooks Dashboard
  2. Click on your webhook endpoint
  3. View Recent webhook attempts
  4. ✓ Green checkmark = successful delivery (HTTP 200)

PayPal​

  1. Go to PayPal Developer Dashboard
  2. Select your app → Webhooks section
  3. Click your webhook to view event log
  4. HTTP 200 status = successful delivery

Common Issues​

Webhooks Not Being Received​

CauseSolution
Wrong URLCheck for typos, ensure HTTPS
Firewall blockingWhitelist payment gateway IPs
REST API disabledEnable in security plugin settings
Plain permalinksSwitch to any other permalink structure

Webhook Returns Error​

CauseSolution
Invalid signing secretRe-copy from gateway dashboard
PHP errorsCheck /wp-content/debug.log
TimeoutIncrease PHP max execution time
Memory limitIncrease PHP memory limit

Payment Works, Subscription Doesn't Activate​

This is always a webhook issue:

  1. Check webhook delivery status in gateway dashboard
  2. Verify signing secret/webhook ID is correct
  3. Enable WP_DEBUG_LOG and check error logs
  4. Ensure all required events are selected

Local Development​

For testing webhooks on localhost:

Stripe CLI​

# Install
brew install stripe/stripe-cli/stripe

# Login
stripe login

# Forward webhooks locally
stripe listen --forward-to localhost/wp-json/paywallwp/v1/stripe-webhook

The CLI provides a temporary signing secret for local testing.

ngrok (for PayPal)​

# Install
brew install ngrok

# Expose local site
ngrok http 80

# Use the ngrok URL for webhooks
# https://abc123.ngrok.io/wp-json/paywallwp/v1/paypal-webhook

Security Notes​

  • Never share signing secrets or webhook IDs publicly
  • Webhooks are cryptographically verified — don't skip verification
  • Monitor webhook logs for unusual activity
  • Use HTTPS exclusively