PayPal Webhooks: Verify Signatures, Test Events and Handle Retries

Option A: the verify-webhook-signature API

POST the headers, your Webhook ID and the event to /v1/notifications/verify-webhook-signature. PayPal answers with verification_status set to SUCCESS or FAILURE. Pass the event through as the raw body text rather than JSON.stringify(JSON.parse(body)): re-serializing can change number formatting or escaping and turn a genuine event into a FAILURE.

const PAYPAL_API = process.env.PAYPAL_API ?? "https://api-m.sandbox.paypal.com"; // live: https://api-m.paypal.com

export async function verifyWithPayPal(
  rawBody: string,
  headers: Record<string, string | string[] | undefined>,
  webhookId: string,
  accessToken: string, // from /v1/oauth2/token, cached until it expires
): Promise<boolean> {
  const h = (name: string) => String(headers[name] ?? "");

  // Splice the raw event in as-is instead of re-serializing it
  const body =
    `{"auth_algo":${JSON.stringify(h("paypal-auth-algo"))},` +
    `"cert_url":${JSON.stringify(h("paypal-cert-url"))},` +
    `"transmission_id":${JSON.stringify(h("paypal-transmission-id"))},` +
    `"transmission_sig":${JSON.stringify(h("paypal-transmission-sig"))},` +
    `"transmission_time":${JSON.stringify(h("paypal-transmission-time"))},` +
    `"webhook_id":${JSON.stringify(webhookId)},` +
    `"webhook_event":${rawBody}}`;

  const res = await fetch(`${PAYPAL_API}/v1/notifications/verify-webhook-signature`, {
    method: "POST",
    headers: { "Content-Type": "application/json", Authorization: `Bearer ${accessToken}` },
    body,
  });
  if (!res.ok) return false;

  const { verification_status } = await res.json();
  return verification_status === "SUCCESS";
}

• Use the Webhook ID and API host of the environment the event came from.
• Cache the OAuth token; don't fetch a new one per webhook.
• It adds one network round trip per event, which is why high-volume listeners verify offline.

Option B: verify offline with CRC32 and the certificate

Build the string transmissionId|timeStamp|webhookId|crc32, where crc32 is the CRC32 of the raw body in decimal, then verify paypal-transmission-sig with SHA-256 RSA against the certificate at paypal-cert-url. Only download certificates from PayPal hosts; otherwise an attacker can point you at their own certificate.

import crypto from "node:crypto";
import crc32 from "buffer-crc32";

const certCache = new Map<string, string>();

async function getCertificate(certUrl: string): Promise<string> {
  const url = new URL(certUrl);
  if (url.protocol !== "https:" || !url.hostname.endsWith(".paypal.com")) {
    throw new Error(`Refusing certificate from ${url.hostname}`);
  }
  if (!certCache.has(certUrl)) {
    const res = await fetch(certUrl);
    if (!res.ok) throw new Error(`Certificate download failed: ${res.status}`);
    certCache.set(certUrl, await res.text());
  }
  return certCache.get(certUrl)!;
}

export async function verifyPayPalOffline(
  rawBody: Buffer, // exact bytes PayPal sent
  headers: Record<string, string | string[] | undefined>,
  webhookId: string,
): Promise<boolean> {
  const h = (name: string) => String(headers[name] ?? "");

  const checksum = crc32.unsigned(rawBody).toString(); // decimal, from raw bytes
  const message = [h("paypal-transmission-id"), h("paypal-transmission-time"), webhookId, checksum].join("|");

  const certificate = await getCertificate(h("paypal-cert-url"));
  return crypto.verify(
    "sha256",
    Buffer.from(message),
    certificate,
    Buffer.from(h("paypal-transmission-sig"), "base64"),
  );
}

• Compute the CRC32 from the raw request body. Parsing and re-stringifying JSON changes the bytes.
• Use the Webhook ID of the current environment (sandbox vs live).
• Cache certificates by URL, and fetch again if verification fails after PayPal rotates them.

How do I verify a PayPal webhook signature?

Either POST the five paypal-* headers, your webhook_id and the unmodified event to /v1/notifications/verify-webhook-signature and accept only verification_status SUCCESS, or verify it yourself: build transmissionId|timeStamp|webhookId|crc32(rawBody), then check paypal-transmission-sig (base64, SHA256withRSA) against the certificate from paypal-cert-url.

What does verify-webhook-signature return?

A JSON object with verification_status set to "SUCCESS" or "FAILURE". It does not return VALID or INVALID. The call needs an OAuth access token and goes to https://api-m.sandbox.paypal.com in sandbox or https://api-m.paypal.com in live.

Why does PayPal webhook verification fail for simulator events?

PayPal's postback verification does not work for mock events sent by the Webhooks simulator. Use simulator events to test parsing and routing, and test signature verification with real sandbox events, for example by completing a sandbox payment.

How many times does PayPal retry a webhook?

Up to 25 times over 3 days, whenever your listener does not answer with a 2xx status or cannot be reached. Store event.id and skip duplicates, and return 200 as soon as the event is safely stored.

How do I see the raw PayPal webhook headers and body?

Subscribe a Hooklistener endpoint URL to the events in the PayPal Developer Dashboard, trigger a sandbox payment, and open the captured request. It shows every paypal-* header and the exact body bytes, which is what signature verification depends on.