PayPal webhooks notify your backend when payments settle, billing agreements change, or disputes arrive. This guide walks through registering a listener, validating authenticity with PayPal’s cryptographic signatures, testing via the simulator, and operating reliably with retry-aware infrastructure.

Step 1: Subscribe a Listener URL

PayPal delivers webhooks only to HTTPS endpoints on port 443. Register your listener either through the PayPal Developer Dashboard or by calling the Webhooks Management API. Each subscription returns a Webhook ID required for signature verification.

In Developer Dashboard → My Apps & Credentials, open your REST application.
Enable Webhooks and add your listener URL (must be HTTPS).
Select the event types you need (for example, PAYMENT.SALE.COMPLETED, BILLING.SUBSCRIPTION.CANCELLED).
Copy the generated Webhook ID and store it securely for runtime verification.

PayPal retries failed deliveries up to 25 times over three days. Your endpoint should always return 2xx quickly—even if downstream processing fails—so PayPal does not suspend the webhook.

Step 2: Test with the Webhooks Simulator

Before listening to live money flows, validate your endpoint using PayPal’s simulator. Mock events help you confirm payload parsing and signature logic, but remember that PayPal does not perform server-to-server postback verification for simulated deliveries.

# Trigger a mock event from the CLI using curl
curl -u CLIENT_ID:SECRET \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/paypal/webhooks",
    "event_types": [{"name": "PAYMENT.SALE.COMPLETED"}]
  }' \
  https://api.sandbox.paypal.com/v1/notifications/webhooks

Use sandbox credentials for simulator tests. When you are ready for live traffic, repeat the subscription process in the live environment with production credentials.

Step 3: Verify PayPal Signatures

PayPal supports two verification strategies. Self-cryptographic verification keeps validation on your servers and works for sandbox and live events. Postback verification lets PayPal validate the payload for you. Always use the raw request body when computing hashes.

Self-cryptographic verification

Extract the headers listed below, compute the CRC32 of the raw JSON body, then verify the signature using the certificate hosted at paypal-cert-url. The resulting string format is transmissionId|timeStamp|webhookId|crc32.

import crypto from "crypto";
import crc32 from "buffer-crc32";
import https from "https";

async function verifyPayPalSignature({
  body,
  headers,
  webhookId,
}: {
  body: Buffer;
  headers: Record<string, string | string[] | undefined>;
  webhookId: string;
}) {
  const transmissionId = headers["paypal-transmission-id"] as string;
  const transmissionTime = headers["paypal-transmission-time"] as string;
  const certUrl = headers["paypal-cert-url"] as string;
  const signature = headers["paypal-transmission-sig"] as string;

  const checksum = crc32.unsigned(body).toString();
  const expected = [transmissionId, transmissionTime, webhookId, checksum].join("|");

  const certificate = await downloadCertificate(certUrl);
  const verifier = crypto.createVerify("RSA-SHA256");
  verifier.update(expected);
  verifier.end();

  const valid = verifier.verify(certificate, signature, "base64");
  if (!valid) {
    throw new Error("Invalid PayPal signature");
  }
}

function downloadCertificate(url: string): Promise<string> {
  return new Promise((resolve, reject) => {
    https
      .get(url, (res) => {
        const chunks: Buffer[] = [];
        res.on("data", (chunk) => chunks.push(chunk));
        res.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
      })
      .on("error", reject);
  });
}

Keep the downloaded certificate cached briefly to reduce latency, but refresh on signature failure.
Use the Webhook ID associated with the current environment (sandbox vs live).
Always compute CRC32 from the raw request body—avoid re-stringifying parsed JSON.

Postback verification

Forward the event payload back to PayPal’s /v1/notifications/verify-webhook-signature endpoint. PayPal responds with VALID or INVALID. Only real events support this workflow—mock simulator events will fail verification.

const response = await fetch(
  "https://api.sandbox.paypal.com/v1/notifications/verify-webhook-signature",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: 'Bearer ' + accessToken,
    },
    body: JSON.stringify({
      auth_algo: headers["paypal-auth-algo"],
      cert_url: headers["paypal-cert-url"],
      transmission_id: headers["paypal-transmission-id"],
      transmission_sig: headers["paypal-transmission-sig"],
      transmission_time: headers["paypal-transmission-time"],
      webhook_event: JSON.parse(body.toString("utf8")),
      webhook_id: webhookId,
    }),
  },
);

const result = await response.json();
if (result.verification_status !== "SUCCESS" && result.verification_status !== "VALID") {
  throw new Error("PayPal postback verification failed");
}

Preserve headers exactly as received; changes can invalidate the signature.
Use sandbox or live endpoints based on the event origin.
Cache OAuth access tokens and refresh before they expire to reduce latency.

Step 4: Process Events Safely

After verification, hydrate business logic cautiously. PayPal can deliver events out of order, so design idempotent handlers and re-fetch authoritative records via the REST API when accuracy matters.

Persist processed event IDs (from event.id) to avoid duplicate work during retries.
Respond with 200 OK once the payload is queued or stored for downstream processing.
Log signature failures with headers and hashed body for incident triage.

Step 5: Launch, Monitor & Troubleshoot

When you upgrade to live mode, repeat your webhook subscription and keep an eye on delivery metrics. PayPal suspends endpoints that consistently return errors or become unreachable.

Launch checklist

Register distinct sandbox and live listeners; never mix credentials.
Ensure your domain is reachable and not blocked by WAF rules.
Set alerts for 4xx/5xx responses and repeated retry attempts.

Troubleshooting tips

Check server logs for TLS handshake errors—PayPal requires strong cipher suites.
Confirm the Webhook ID matches the subscription for the current environment.
Use PayPal resend tools to replay missed events after fixes.

Summary Table

Step	Action	Notes
Register	Add HTTPS listener via dashboard or API	Save Webhook ID; PayPal retries 25 times/3 days
Test	Use Webhooks simulator	Validates parsing; postback not supported
Verify	Self-crypto or postback verification	Always use raw body + matching Webhook ID
Process	Run business logic, store event ID	Respond 200 OK to avoid further retries
Monitor	Watch delivery logs & retries	Resend from dashboard after fixes

Build Faster with Hooklistener

Hooklistener captures PayPal webhook traffic alongside Stripe, Shopify, and Slack callbacks. Forward sandbox events to local tunnels, store payloads for regression testing, and receive alerts before PayPal disables misbehaving listeners.

✓Centralize sandbox and live webhook URLs with auditing

✓Replay PayPal payloads to verify signature updates

✓Share event history and headers across engineering teams

✓Get notified when retries spike or responses degrade

Start Debugging PayPal Webhooks →

PayPal Webhooks Guide: Secure Verification & Listener Setup