PayPal Guides de test webhook

Replay + helper signature (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. Setup app locale

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. Lancer InstaTunnel

instatunnel 3000 --subdomain paypal-dev

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

3. Champs provider a coller

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

4. Envoyer un evenement de test

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. Verifier la 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. Retrys et idempotence

• 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. Echecs courants et corrections rapides