Verify PayPal webhooks

Verify that a webhook really came from PayPal before acting on it.

Identifier	'paypal'
Import	import { verifyPayPal } from 'verihook/paypal'
Headers	paypal-transmission-id paypal-transmission-time paypal-transmission-sig paypal-cert-url paypal-auth-algo
Signature	RSA-SHA256 signature of <transmission id>|<time>|<webhook id>|<CRC32 of body>, checked with PayPal’s signing certificate.
Replay window	None (the provider sends no timestamp)
result.eventType	the body’s event_type, e.g. PAYMENT.CAPTURE.COMPLETED

Get your secret

The Webhook ID (not a secret): in the PayPal Developer Dashboard, open Apps & Credentials, select the app and find the ID in its webhooks list. Pass it as the secret or as { webhookId }. To avoid fetching the certificate, pass the PEM certificate as the secret and the ID as webhookId.

Store it in an environment variable (PAYPAL_WEBHOOK_ID below) and never commit it.

Verify a request

import { verifyPayPal } from 'verihook/paypal';

export async function POST(request: Request) {
  const result = await verifyPayPal(request, process.env.PAYPAL_WEBHOOK_ID!);

  if (!result.valid) {
    console.warn(result.code, result.reason, result.hint);
    return new Response('Invalid signature', { status: 401 });
  }

  console.log(result.eventType, result.event);
  return Response.json({ received: true });
}

request can be a Fetch Request or { headers, body, url? } with the raw body. verifyWebhook('paypal', request, secret) from verihook does the same. Read why the raw body matters if verification fails behind a body parser.

Framework examples

Next.js

app/api/webhooks/paypal/route.ts

import { createWebhookHandler } from 'verihook/next';

export const POST = createWebhookHandler('paypal', process.env.PAYPAL_WEBHOOK_ID!, async (payload, result) => {
  // Runs only for a valid signature
  console.log(result.eventType, result.event);
});

Express

import express from 'express';
import { verihookExpress, type VerihookRequestAdditions } from 'verihook/express';

const app = express();

// Register before express.json(), or keep express.json() off this route
app.post('/webhooks/paypal', verihookExpress('paypal', process.env.PAYPAL_WEBHOOK_ID!), (req, res) => {
  const { eventType, event } = (req as typeof req & VerihookRequestAdditions).verihook!;
  res.json({ received: true });
});

Fastify

import Fastify from 'fastify';
import { verihookFastify, verihookRawBody, type VerihookFastifyRequest } from 'verihook/fastify';

const app = Fastify();
await app.register(verihookRawBody);

app.post('/webhooks/paypal', { preHandler: verihookFastify('paypal', process.env.PAYPAL_WEBHOOK_ID!) }, async (request) => {
  const { eventType, event } = (request as typeof request & VerihookFastifyRequest).verihook!;
  return { received: true };
});

Hono

import { Hono } from 'hono';
import { verihookHono, type VerihookVariables } from 'verihook/hono';

const app = new Hono<{ Bindings: { PAYPAL_WEBHOOK_ID: string }; Variables: VerihookVariables }>();

app.post('/webhooks/paypal', verihookHono('paypal', (c) => c.env.PAYPAL_WEBHOOK_ID), (c) => {
  const { eventType, event } = c.get('verihook');
  return c.json({ received: true });
});

NestJS

// main.ts: NestFactory.create(AppModule, { rawBody: true })
import { Controller, Post, Req, UseGuards } from '@nestjs/common';
import { createVerihookGuard, type VerihookNestRequest } from 'verihook/nestjs';

@Controller('webhooks')
export class WebhooksController {
  @Post('paypal')
  @UseGuards(createVerihookGuard('paypal', process.env.PAYPAL_WEBHOOK_ID!))
  handle(@Req() req: VerihookNestRequest) {
    const { eventType, event } = req.verihook!;
  }
}

Nuxt / h3

server/api/webhooks/paypal.post.ts

import { createWebhookHandler } from 'verihook/h3';

export default defineEventHandler(
  createWebhookHandler('paypal', process.env.PAYPAL_WEBHOOK_ID!, async (payload, result) => {
    console.log(result.eventType);
  }),
);

SvelteKit

src/routes/webhooks/paypal/+server.ts

import { env } from '$env/dynamic/private';
import { createWebhookHandler } from 'verihook/sveltekit';

export const POST = createWebhookHandler('paypal', () => env.PAYPAL_WEBHOOK_ID, async (payload, result) => {
  console.log(result.eventType);
});

Remix / React Router

app/routes/webhooks.paypal.ts

import { createWebhookHandler } from 'verihook/remix';

export const action = createWebhookHandler('paypal', process.env.PAYPAL_WEBHOOK_ID!, async (payload, result) => {
  console.log(result.eventType);
});

Astro

src/pages/api/webhooks/paypal.ts

import { createWebhookHandler } from 'verihook/astro';

export const prerender = false;
export const POST = createWebhookHandler('paypal', import.meta.env.PAYPAL_WEBHOOK_ID, async (payload, result) => {
  console.log(result.eventType);
});

AWS Lambda

import { createWebhookHandler } from 'verihook/lambda';

export const handler = createWebhookHandler('paypal', process.env.PAYPAL_WEBHOOK_ID!, async (payload, result) => {
  console.log(result.eventType);
});

Each adapter responds 401 to an invalid signature, 413 to a body over maxBodySize (2 MB by default) and 200 to a duplicate when you pass a dedupeStore.

Things to know

• Verification fetches PayPal’s certificate from paypal-cert-url over HTTPS. Only PayPal API hosts are allowed, and certificates are cached in memory.
• Sandbox and live webhooks have different IDs.

Testing

PayPal signs with its own private key, so verihook/testing can’t create PayPal webhooks. Use the provider’s sandbox or simulator, or mock verifyPayPal in unit tests.

Troubleshooting

Failed results carry a code and often a hint with the likely cause. See Troubleshooting for each error code.

PayPal’s webhook documentation