Webhook Guide

PayPal Webhook Testing

Payment event webhooks and simulator testing

Quick path: CLI helper commands

Use these first to avoid setup mistakes, then follow the full provider steps below.

instatunnel webhook init --provider paypal --port 3000 --path /webhooks/paypal

instatunnel webhook verify --provider paypal --secret-env PAYPAL_WEBHOOK_ID

instatunnel webhook test --provider paypal

If you run into provider-specific issues, use the full checklist sections below.

1. Local app setup

Create a local webhook endpoint at: /webhooks/paypal

import express from 'express'

const app = express()
app.use(express.json())

app.post('/webhooks/paypal', async (req, res) => {
  // 1) Capture PayPal transmission headers
  // 2) POST to /v1/notifications/verify-webhook-signature with your webhook_id
  // 3) Accept event only when verification_status === 'SUCCESS'
  console.log('paypal event:', req.body.event_type)
  res.status(200).send('ok')
})

app.listen(3000, () => console.log('listening on :3000'))

2. Run InstaTunnel command

instatunnel 3000 --subdomain paypal-dev

Keep a fixed subdomain so your provider dashboard URL does not keep changing.

3. Provider config fields to paste

Field	Value	Where/notes
Webhook URL	`{{WEBHOOK_URL}}`	PayPal Developer Dashboard > Webhooks
Events	`PAYMENT.CAPTURE.COMPLETED (example)`	Subscribe to only required event types
Webhook ID	`WH-...`	Store as PAYPAL_WEBHOOK_ID for signature verification calls
Environment	`Sandbox first`	Use simulator in sandbox before production

Use the helper below to generate exact values with your chosen subdomain and path.

One-Click Webhook Setup Helper

Generate copy-ready tunnel command, webhook URL, and provider config values.

Local portSubdomainEndpoint path

Run InstaTunnel

instatunnel 3000 --subdomain paypal-dev

Webhook URL

https://paypal-dev.instatunnel.my/webhooks/paypal

Provider field	Value to paste	Notes
Webhook URL	`https://paypal-dev.instatunnel.my/webhooks/paypal`	PayPal Developer Dashboard > Webhooks
Events	`PAYMENT.CAPTURE.COMPLETED (example)`	Subscribe to only required event types
Webhook ID	`WH-...`	Store as PAYPAL_WEBHOOK_ID for signature verification calls
Environment	`Sandbox first`	Use simulator in sandbox before production

Tip: keep one stable subdomain per provider to avoid reconfiguring dashboards.

4. Send test event

Use PayPal Webhook Simulator in sandbox to send test events.
Validate your endpoint returns 200 and event body is parsed.
For simulator events, self-verify with your webhook ID. For real events, call verify-webhook-signature and require verification_status=SUCCESS.

5. Verify signature

Verify this header on every request: paypal-transmission-sig (plus transmission metadata headers)

// Send verification request to PayPal API
POST /v1/notifications/verify-webhook-signature
{
  transmission_id,
  transmission_time,
  cert_url,
  auth_algo,
  transmission_sig,
  webhook_id: process.env.PAYPAL_WEBHOOK_ID,
  webhook_event: req.body
}
// accept only when verification_status === "SUCCESS"

6. Retries and idempotency

Use PayPal event ID as idempotency key.
Respond quickly with 200 after enqueueing background processing.
Treat all webhook deliveries as at-least-once and replay-safe.

7. Common failures and quick fixes

Verification status not SUCCESS

Check webhook ID/environment mismatch and transmission headers.

Simulator event not received

Confirm sandbox app uses current tunnel URL and active webhook subscription.

Simulator verification confusion

Simulator mock events cannot be verified via verify-webhook-signature endpoint; use real events for API verification tests.

Duplicate processing

Deduplicate by event ID before writing side effects.