Adds Zod validation for webhook payloads #377

infomiho · 2025-02-19T13:59:54Z

Adds runtime validation for all webhook payloads instead of relying on type assertions.

The idea was:

write Zod schemas for all the data we 100% need
parse the data and return it in format { eventName, data } which helps when you check for eventName you are sure of the type of the data object

Signed-off-by: Mihovil Ilakovac <[email protected]>

infomiho · 2025-02-20T09:17:09Z

template/app/src/payment/lemonSqueezy/webhook.ts

  } catch (err) {
+    if (err instanceof UnhandledWebhookEventError) {


I wasn't sure if we wanted to return something other than 200 if we receive a request for a webhook event we don't handle.

I guess we could, but we shouldn't be receiving any webhooks we don't explicitly request from the Stripe dashboard settings. Maybe the console.error is enough?

we shouldn't be receiving any webhooks we don't explicitly request from the Stripe

Yes, I understand but I kept seeing errors for some of the hooks in the e2e tests so I implemented this bit - this way we are just "ignoring" the extra webhook calls.

I think we should probably return an error code, right? This way, we explicitly tell Stripe (hey, we couldn't handle this). It probably makes things easier for people requesting refunds etc.

Yes, I understand but I kept seeing errors for some of the hooks in the e2e tests so I implemented this bit - this way we are just "ignoring" the extra webhook calls.

I didn't get this part. Why would they be sending events we didn't request? If that's the case, all the more reason to return 400 or something similar (e.g., 422 - unprocessable content).

infomiho · 2025-02-20T09:17:48Z

template/app/src/payment/stripe/webhook.ts

-      // In development, it is likely that you will receive other events that you are not handling, and that's fine. These can be ignored without any issues.
-      console.error('Unhandled event type: ', event.type);
+    if (err instanceof UnhandledWebhookEventError) {
+      return response.status(200).json({ received: true });


Same thing as in https://github.com/wasp-lang/open-saas/pull/377/files#r1963148873

infomiho · 2025-02-20T09:33:37Z

template/app/src/payment/stripe/webhookPayload.ts

+    throw new Error('Invalid Stripe Event');
+  });
+  switch (event.type) {
+    case 'checkout.session.completed':


I tried doing stuff like this to reduce the code duplication, but I couldn't get the exact types (discriminate unions):

const eventToSchema = { 'checkout.session.completed': sessionCompletedDataSchema, 'invoice.paid': invoicePaidDataSchema, 'customer.subscription.updated': subscriptionUpdatedDataSchema, 'customer.subscription.deleted': subscriptionDeletedDataSchema, } as const; function isSchemaDefinedForEvent(eventType: string): eventType is keyof typeof eventToSchema { return eventType in eventToSchema; } if (!isSchemaDefinedForEvent(event.type)) { throw new UnhandledWebhookEventError(event.type); } const schema = eventToSchema[event.type]; const data = await schema.parseAsync(event.data.object).catch(handleParsingError); return { eventName: event.type, data };

this is starting to look more complicated than it needs to be.

But wouldn't using a Record type be clearer, where the key type is Stripe.Event? That way you wouldn't have to use eventType is keyof typeof eventToSchema

this is starting to look more complicated than it needs to be.

You mean the code in the PR or the code in this comment?

@infomiho Yeah, this is a classic problem. Once you get down to a union type, you can't deunionize it (if it's unknown at compile time).

You could make it work by passing the event.type into a function, and then querying for the correct schema inside. At least I think this would work, I could try tomorrow. On second thought, maybe not. I'd have to play around.

But, I think I agree with @vincanger - this is a lot for an average OpenSaas user.

@vincanger Btw, to answer your question, he can't use Record<Stripe.Event, ...> because Stripe.Event is an alias for a string (they underspecified the type).

For reducing duplication, we could focus on each case's body and perhaps extract a function:

switch (event.type) { // ... case 'payment_intent.succeeded': const paymentIntent = await parseStripeEventData(paymentIntentSucceededDataSchema, event.data.object); return { eventName: event.type, data: paymentIntent }; // option 1 case 'customer.subscription.updated': return { eventName: event.type, data: parseStripeEventData(subscriptionDeletedDataSchema, event.data.object), }; // option 2 case 'customer.subscription.deleted': const deletedSubscription = await parseStripeEventData( subscriptionDeletedDataSchema, event.data.object ); return { eventName: event.type, data: deletedSubscription }; } function parseStripeEventData<Z extends z.AnyZodObject>( schema: Z, rawStripeEvent: unknown ): Promise<z.infer<Z>> { return schema.parseAsync(rawStripeEvent).catch((e) => { console.error(e); throw new Error('Error parsing Stripe event object'); }); }

But again, since this is a template, and the types here are pretty scary, I'd probably keep the duplication.

I am even on the edge of suggesting we hold off with introducing Zod to webhooks, but I can't judge is it to HC or not. I'll leave that to @vincanger.

vincanger

Looks good. I'd say we merge the payment_intent.succeeded webhook addition and add that first, before merging though.

vincanger · 2025-02-20T09:10:51Z

template/app/src/payment/stripe/webhook.ts

@@ -10,47 +10,75 @@ import { emailSender } from 'wasp/server/email';
 import { assertUnreachable } from '../../shared/utils';
 import { requireNodeEnvVar } from '../../server/utils';
 import { z } from 'zod';
+import {
+  InvoicePaidData,
+  parseWebhookPayload,


should we separate and import types at the type of the file, as we've been doing?

You mean import the types at the top of the file? I don't see that we did that in this file e.g.

import { type MiddlewareConfigFn, HttpError } from 'wasp/server';

is on top.

I've added the import type bit for the types.

ah true, this won't apply for zod types as they're runtime specific, right?

this won't apply for zod types as they're runtime specific, right?

I'm not following sorry :) What do mean exactly that won't apply to Zod types?

vincanger · 2025-02-20T09:11:29Z

template/app/src/payment/stripe/webhook.ts

+      case 'customer.subscription.deleted':
+        await handleCustomerSubscriptionDeleted(payload.data, prismaUserDelegate);
+        break;
+      default:


We're missing payment_intent.succeeded but I think that's still awaiting to be merged in another PR...

I've added the handling of the payment_intent.succeeded hook 👍

Just to double check. How come this was missing and is it possible we missed something else?

It was a parallel PR of introducing payment_intent.succeeded event #375

vincanger · 2025-02-20T09:43:30Z

template/app/src/payment/lemonSqueezy/webhook.ts

  } catch (err) {
+    if (err instanceof UnhandledWebhookEventError) {


I guess we could, but we shouldn't be receiving any webhooks we don't explicitly request from the Stripe dashboard settings. Maybe the console.error is enough?

vincanger

tested it out and looking good.

vincanger · 2025-02-20T19:40:31Z

template/app/src/payment/stripe/webhook.ts

@@ -10,47 +10,75 @@ import { emailSender } from 'wasp/server/email';
 import { assertUnreachable } from '../../shared/utils';
 import { requireNodeEnvVar } from '../../server/utils';
 import { z } from 'zod';
+import {
+  InvoicePaidData,
+  parseWebhookPayload,


ah true, this won't apply for zod types as they're runtime specific, right?

sodic

Nice work!

I left some comments. Don't think I found anything wrong, but I had some questions.

Note

Btw, in the future, I recommend doing refactors/non-functional changes in a separate PR. Git often doesn't realize something was moved and important changes can slip through unnoticed.

I've only started doing this very recently after reading this great article: https://mtlynch.io/code-review-love. It's a must-read. Although I was and still am guilty of some of the things he mentions

template/app/src/payment/lemonSqueezy/webhookPayload.ts

template/app/src/payment/lemonSqueezy/webhook.ts

sodic · 2025-02-25T23:42:41Z

template/app/src/payment/stripe/webhookPayload.ts

+    throw new Error('Invalid Stripe Event');
+  });
+  switch (event.type) {
+    case 'checkout.session.completed':


@infomiho Yeah, this is a classic problem. Once you get down to a union type, you can't deunionize it (if it's unknown at compile time).

You could make it work by passing the event.type into a function, and then querying for the correct schema inside. At least I think this would work, I could try tomorrow. On second thought, maybe not. I'd have to play around.

But, I think I agree with @vincanger - this is a lot for an average OpenSaas user.

@vincanger Btw, to answer your question, he can't use Record<Stripe.Event, ...> because Stripe.Event is an alias for a string (they underspecified the type).

sodic · 2025-02-25T23:46:31Z

template/app/src/payment/stripe/webhookPayload.ts

+    throw new Error('Invalid Stripe Event');
+  });
+  switch (event.type) {
+    case 'checkout.session.completed':


For reducing duplication, we could focus on each case's body and perhaps extract a function:

switch (event.type) { // ... case 'payment_intent.succeeded': const paymentIntent = await parseStripeEventData(paymentIntentSucceededDataSchema, event.data.object); return { eventName: event.type, data: paymentIntent }; // option 1 case 'customer.subscription.updated': return { eventName: event.type, data: parseStripeEventData(subscriptionDeletedDataSchema, event.data.object), }; // option 2 case 'customer.subscription.deleted': const deletedSubscription = await parseStripeEventData( subscriptionDeletedDataSchema, event.data.object ); return { eventName: event.type, data: deletedSubscription }; } function parseStripeEventData<Z extends z.AnyZodObject>( schema: Z, rawStripeEvent: unknown ): Promise<z.infer<Z>> { return schema.parseAsync(rawStripeEvent).catch((e) => { console.error(e); throw new Error('Error parsing Stripe event object'); }); }

But again, since this is a template, and the types here are pretty scary, I'd probably keep the duplication.

I am even on the edge of suggesting we hold off with introducing Zod to webhooks, but I can't judge is it to HC or not. I'll leave that to @vincanger.

template/app/src/payment/stripe/webhook.ts

sodic

Nice work, left some more comments but most big stufff is resolved.

@vincanger Please come weigh in on the unresolved threads that require your expertise.

sodic · 2025-04-15T10:39:15Z

template/app/src/payment/lemonSqueezy/webhook.ts

    }
  }
 };

+function parseRequestBody(request: express.Request): string {


This function and parseWebhookPayload seem very similar to Stripe's constructStripeEvent. Should we make the naming consistent?

sodic · 2025-04-15T10:42:02Z

template/app/src/payment/lemonSqueezy/webhookPayload.ts

+// This is a subtype of Order type from "@lemonsqueezy/lemonsqueezy.js"
+// specifically Order['data']


If it's the type of Order['data'], then it's not a subtype. Same applies to subscriptionData. This confused me at first because I only read "subtype" and didn't understand why we're renaming them from X to XData.

sodic · 2025-04-15T10:45:04Z

template/app/src/payment/lemonSqueezy/webhookPayload.ts

+
+export type OrderData = z.infer<typeof orderDataSchema>;
+
+const genericEventSchema = z.object({


Should we document where this type comes from as well?

sodic · 2025-04-15T10:48:53Z

template/app/src/payment/lemonSqueezy/webhook.ts

  } catch (err) {
+    if (err instanceof UnhandledWebhookEventError) {


I think we should probably return an error code, right? This way, we explicitly tell Stripe (hey, we couldn't handle this). It probably makes things easier for people requesting refunds etc.

Yes, I understand but I kept seeing errors for some of the hooks in the e2e tests so I implemented this bit - this way we are just "ignoring" the extra webhook calls.

I didn't get this part. Why would they be sending events we didn't request? If that's the case, all the more reason to return 400 or something similar (e.g., 422 - unprocessable content).

sodic · 2025-04-15T10:51:14Z

template/app/src/payment/stripe/webhook.ts

+    const lineItems = await subscriptionItemsSchema.parseAsync(lineItemsRaw);
+
+    return lineItems;


I advise just returning it directly.

sodic · 2025-04-15T10:51:55Z

template/app/src/payment/stripe/webhook.ts

-  }
-  if (result.data.data.length > 1) {
+function extractPriceId(items: SubscsriptionItems): string {
+  if (items.data.length > 1) {


Do we also need a check for an empty array?

infomiho force-pushed the miho-webhooks-runtime-validations branch from 06458e3 to 4dc0c4b Compare February 19, 2025 14:02

infomiho marked this pull request as ready for review February 19, 2025 14:06

infomiho force-pushed the miho-webhooks-runtime-validations branch from 7760552 to 4cc1b39 Compare February 19, 2025 15:31

Adds Zod validation for webhook payloads

a8f52f2

Signed-off-by: Mihovil Ilakovac <[email protected]>

infomiho force-pushed the miho-webhooks-runtime-validations branch from 5750330 to a8f52f2 Compare February 19, 2025 15:57

infomiho requested review from vincanger and sodic February 20, 2025 09:16

infomiho commented Feb 20, 2025

View reviewed changes

Cleanup

20ee20a

infomiho commented Feb 20, 2025

View reviewed changes

infomiho added 2 commits February 20, 2025 10:38

Update Lemon Squeezy validation

ad41d60

Update Lemon Squeezy validation #2

b7de406

vincanger requested changes Feb 20, 2025

View reviewed changes

infomiho added 4 commits February 20, 2025 10:46

Add extra comments above the validation schemas

ef496af

Merge branch 'main' into miho-webhooks-runtime-validations

a969544

Drop redundant validation

77ad7a4

Adds type imports

e40c1e4

vincanger approved these changes Feb 20, 2025

View reviewed changes

infomiho mentioned this pull request Feb 21, 2025

Dry up subscription status #382

Merged

Merge branch 'main' into miho-webhooks-runtime-validations

40afc5e

sodic reviewed Feb 26, 2025

View reviewed changes

infomiho added 2 commits February 28, 2025 12:36

Merge branch 'main' into miho-webhooks-runtime-validations

e628733

PR comments

98047b7

infomiho requested a review from sodic February 28, 2025 17:13

infomiho self-assigned this Apr 7, 2025

sodic reviewed Apr 15, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adds Zod validation for webhook payloads #377

Adds Zod validation for webhook payloads #377

infomiho commented Feb 19, 2025 •

edited

Loading

infomiho Feb 20, 2025

vincanger Feb 20, 2025

infomiho Feb 20, 2025 •

edited

Loading

sodic Apr 15, 2025

infomiho Feb 20, 2025

infomiho Feb 20, 2025

vincanger Feb 20, 2025 •

edited

Loading

infomiho Feb 21, 2025

sodic Feb 25, 2025 •

edited

Loading

sodic Feb 25, 2025

vincanger left a comment

vincanger Feb 20, 2025

infomiho Feb 20, 2025

vincanger Feb 20, 2025

infomiho Feb 21, 2025

vincanger Feb 20, 2025

infomiho Feb 20, 2025

sodic Feb 25, 2025

infomiho Feb 28, 2025

vincanger Feb 20, 2025

vincanger left a comment

vincanger Feb 20, 2025

sodic left a comment

sodic Feb 25, 2025 •

edited

Loading

sodic Feb 25, 2025

sodic left a comment

sodic Apr 15, 2025

sodic Apr 15, 2025 •

edited

Loading

sodic Apr 15, 2025

sodic Apr 15, 2025

sodic Apr 15, 2025

sodic Apr 15, 2025

		} catch (err) {
		if (err instanceof UnhandledWebhookEventError) {

		// This is a subtype of Order type from "@lemonsqueezy/lemonsqueezy.js"
		// specifically Order['data']


		export type OrderData = z.infer<typeof orderDataSchema>;

		const genericEventSchema = z.object({

		const lineItems = await subscriptionItemsSchema.parseAsync(lineItemsRaw);

		return lineItems;

Adds Zod validation for webhook payloads #377

Are you sure you want to change the base?

Adds Zod validation for webhook payloads #377

Conversation

infomiho commented Feb 19, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

infomiho Feb 20, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vincanger Feb 20, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sodic Feb 25, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vincanger left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vincanger left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sodic left a comment

Choose a reason for hiding this comment

sodic Feb 25, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sodic left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sodic Apr 15, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

infomiho commented Feb 19, 2025 •

edited

Loading

infomiho Feb 20, 2025 •

edited

Loading

vincanger Feb 20, 2025 •

edited

Loading

sodic Feb 25, 2025 •

edited

Loading

sodic Feb 25, 2025 •

edited

Loading

sodic Apr 15, 2025 •

edited

Loading