PayPal Webhook-Testguides

Replay + Signatur-Helper (Dashboard)

Open /dashboard or /dashboard/tunnels and use Webhook Command Center for this provider. It gives one-click replay and signature verification helpers.

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

curl -i -X POST "https://YOUR-SUBDOMAIN.instatunnel.my/webhooks/paypal" -H "Content-Type: application/json" --data-binary @sample-paypal.json

Required signature header: paypal-transmission-sig (plus transmission metadata headers)

1. Lokales 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. InstaTunnel-Befehl ausfuhren

instatunnel 3000 --subdomain paypal-dev

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

3. Provider-Felder zum Einfugen

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

4. Testevent senden

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

5. Signatur prufen

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 und Idempotenz

• 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. Haufige Fehler und schnelle Fixes