Add webhook sample infrastructure (#1677)

Makefile

@@ -2,6 +2,7 @@
 update-version:
 	@echo "$(VERSION)" > VERSION
 	@perl -pi -e 's|"version": "[.\-\d\w]+"|"version": "$(VERSION)"|' package.json
+	@find . -name 'package.json' -exec perl -pi -e 's|"stripe": "[\^\d\w.]*?"|"stripe": "^$(VERSION)"|' {} +
 
 codegen-format:
 	yarn && yarn fix && yarn build

examples/webhook-signing/.env.example

@@ -1,3 +1,3 @@
 # Stripe keys
 STRIPE_SECRET_KEY=
-STRIPE_WEBHOOK_SECRET=
+STRIPE_WEBHOOK_SECRET=whsec_0000000000000000000000000000000000000000000000000000000000000000

examples/webhook-signing/node-koa/.eslintrc.js → examples/webhook-signing/.eslintrc.js

@@ -2,6 +2,9 @@ module.exports = {
   env: {
     node: true,
   },
+  parserOptions: {
+    warnOnUnsupportedTypeScriptVersion: false,
+  },
   root: true,
   parser: '@typescript-eslint/parser',
   plugins: ['@typescript-eslint', 'prettier'],

examples/webhook-signing/.gitignore

@@ -1,2 +1,5 @@
+*/tsconfig.json
+**/.eslintrc.js
+**/package-lock.json
 .env
 express-ts.js

examples/webhook-signing/README.md

@@ -2,30 +2,28 @@
 
 Verify the events that Stripe sends to your webhook endpoints. Additional details in the Stripe [docs](https://stripe.com/docs/webhooks/signatures).
 
-You can find a Node.js TypeScript server example in [stripe-samples](https://github.com/stripe-samples/accept-a-payment/tree/main/custom-payment-flow/server/node-typescript).
+Available examples:
+- [`express`](./express) - Express 4
+- [`koa`](./koa) - Koa 2
 
 ### Requirements
 
 You’ll need the following:
 
-- [Node.js](http://nodejs.org) >=10.0.0
+- [Node.js](http://nodejs.org) >=14.0.0
 - Stripe account to accept payments ([sign up](https://dashboard.stripe.com/register) for free).
 - [Stripe CLI](https://github.com/stripe/stripe-cli) or [ngrok](https://ngrok.com/) to tunnel requests to your local server.
 
-### Setup
-
-In this directory (`cd examples/webhook-signing/`), copy the environment variables file:
-
-    cp .env.example .env
-
-Update `.env` with your own [Stripe API keys](https://dashboard.stripe.com/account/apikeys).
-
 ### Install and run
 
+In the sample directory (`cd examples/webhook-signing/express`).
+
 Install dependencies:
 
     npm install
 
+Update `.env` with your own [Stripe API keys](https://dashboard.stripe.com/account/apikeys).
+
 Next, follow [these installation steps](https://github.com/stripe/stripe-cli#installation) to install the Stripe CLI which we'll use for webhook forwarding.
 
 After the installation has finished, authenticate the CLI with your Stripe account:
@@ -42,13 +40,28 @@ The Stripe CLI will let you know that webhook forwarding is ready and output you
 
 Copy the webhook signing secret (`whsec_xxx`) to your `.env` file.
 
-In a separate terminal window, start the local server:
+In a separate terminal window, start the local sample server:
 
-    npm run vanilla # Runs the vanilla JavaScript example.
-    npm run typescript # Compiles and runs the TypeScript example.
+    `./main.ts`
 
 In another separate terminal window, trigger an event, for example:
 
     stripe trigger payment_intent.succeeded
 
 You should now see some webhook event details being logged to your Node.js console.
+
+## Developing
+
+To add a new example:
+1. Create a new subfolder using the server library name
+2. Copy `package.json` from one of the existing samples. Remove extra dependencies.
+3. Create a `main.ts` file with sample server code and run `chmod +x main.ts` so it's directly executable.
+4. The `main.ts` has to follow some rules:
+  1. Written in typescript using `import .. from ..` import syntax.
+  2. Must have `#!/usr/bin/env -S npm run-script run` header to be directly runable.
+  3. Must print `Webhook endpoint available at <url>` when the server is started.
+  4. Must return `{"received":true}` and 200 status code for `charge.succeeded` event.
+5. Test your example
+  1. `cd examples/webhook-signing/test`
+  2. `./main.ts ../<your test directory>`
+  3. Add a test to `/tests/Integration.spec.ts`

examples/webhook-signing/typescript-node-express/express-ts.ts → examples/webhook-signing/express/main.ts

@@ -1,6 +1,9 @@
+#!/usr/bin/env -S npm run-script run
+
 import Stripe from 'stripe';
 import express from 'express';
 import env from 'dotenv';
+import {AddressInfo} from 'net';
 
 env.config();
 
@@ -65,6 +68,9 @@ app.post(
   }
 );
 
-app.listen(3000, (): void => {
-  console.log('Example app listening on port 3000!');
-});
+const server = app.listen();
+console.log(
+  `Webhook endpoint available at http://localhost:${
+    (<AddressInfo>server.address()).port
+  }/webhook`
+);

examples/webhook-signing/express/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "webhook-signing-example-express",
+  "version": "1.0.0",
+  "description": "Express webhook parsing sample",
+  "repository": {},
+  "main": "./main.ts",
+  "scripts": {
+    "run": "ts-node-transpile-only ./main.ts",
+    "prepare": "../prepare.sh"
+  },
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "dotenv": "^8.2.0",
+    "express": "^4.17.1",
+    "koa": "^2.14.1",
+    "stripe": "^11.9.1"
+  },
+  "devDependencies": {
+    "eslint": "^8.33.0",
+    "@types/koa": "^2.13.5",
+    "@types/koa-bodyparser": "^4.3.10",
+    "@types/node": "^13.1.4",
+    "typescript": "^4.8.3"
+  }
+}

examples/webhook-signing/node-koa/koa.js → examples/webhook-signing/koa/main.ts

@@ -1,7 +1,10 @@
-const Stripe = require('stripe');
-const Koa = require('koa');
-const bodyParser = require('koa-bodyparser');
-const env = require('dotenv');
+#!/usr/bin/env -S npm run-script run
+
+import Stripe from 'stripe';
+import Koa from 'koa';
+import bodyParser from 'koa-bodyparser';
+import env from 'dotenv';
+import {AddressInfo} from 'net';
 
 const app = new Koa();
 
@@ -12,9 +15,8 @@ const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
   apiVersion: '2022-11-15',
 });
 
-const handleWebhook = async (ctx, next) => {
+const handleWebhook = async (ctx: Koa.ParameterizedContext, next: Koa.Next) => {
   const sig = ctx.request.headers['stripe-signature'];
-
   let event;
 
   try {
@@ -56,10 +58,14 @@ app.use(async (ctx, next) => {
   if (ctx.request.path === '/webhook') {
     return handleWebhook(ctx, next);
   }
-  const name = ctx.request.body?.name ?? 'world';
+  const name = ctx.request.body?.['name'] ?? 'world';
   ctx.body = `hello ${name}, you hit ${ctx.request.path}`;
 });
 
-app.listen(3000, () => {
-  console.log('Example app listening on port 3000!');
-});
+const server = app.listen();
+
+console.log(
+  `Webhook endpoint available at http://localhost:${
+    (<AddressInfo>server.address()).port
+  }/webhook`
+);

examples/webhook-signing/koa/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "webhook-signing-example-koa",
+  "version": "1.0.0",
+  "description": "",
+  "main": "./main.ts",
+  "scripts": {
+    "run": "ts-node-transpile-only ./main.ts",
+    "prepare": "../prepare.sh"
+  },
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "dotenv": "^8.2.0",
+    "koa": "^2.14.1",
+    "stripe": "^11.9.1",
+    "koa-bodyparser": "^4.3.0"
+  },
+  "devDependencies": {
+    "eslint": "^8.33.0",
+    "@types/node": "^13.1.4",
+    "@types/koa": "^2.13.5",
+    "@types/koa-bodyparser": "^4.3.10",
+    "typescript": "^4.8.3",
+    "ts-node": "^10.9.1"
+  }
+}