PayPal Guias de prueba de webhooks

Replay + helper de firma (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 local de app

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. Ejecutar comando InstaTunnel

instatunnel 3000 --subdomain paypal-dev

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

3. Campos a pegar en proveedor

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

4. Enviar evento de prueba

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. Verificar firma

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. Reintentos e idempotencia

• 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. Fallos comunes y solucion rapida