Makerkit handles five webhooks from Stripe and stores "just enough" data into the organization's entity to function correctly.
The Stripe's webhooks topics are defined here at app/core/stripe/stripe-webhooks.enum.ts
:
export enum StripeWebhooks {
Completed = 'checkout.session.completed',
SubscriptionDeleted = 'customer.subscription.deleted',
SubscriptionUpdated = 'customer.subscription.updated',
}
To handle webhooks, we created an API route at routes/resources/stripe/webhook.ts
.
This route is responsible for:
- Validating that the webhook is coming from Stripe
- Routing the webhook to its handler
Validating Stripe's Webhooks
To validate the webhook, we do the following:
- get the header 'stripe-signature'
- create a Stripe instance
- get the raw body
- call
constructEvent
to validate and build an event object sent by Stripe. When this fails, it will throw an error
const signature = req.headers['stripe-signature'];
// verify signature header is not missing
if (!signature) {
return throwBadRequestException(res);
}
const rawBody = await getRawBody(req);
const stripe = await getStripeInstance();
const event = stripe.webhooks.constructEvent(
rawBody,
signature,
webhookSecretKey
);
Handling Stripe's Webhooks
After validating the webhook, we can now handle the webhook type relative to its topic:
switch (event.type) {
case StripeWebhooks.Completed: {
// handle completed
}
case StripeWebhooks.AsyncPaymentSuccess: {
// handle async payment success
}
}
As described above, we handle 5 events:
Completed
: the checkout session was completed (but payment may not have arrived yet if it's asynchronous)SubscriptionDeleted
: the subscription was deleted by the customerSubscriptionUpdated
: the subscription was updated by the customer
Checkout Completed
When a user completes the checkout session, we create the subscription
object on the currently connected user's organization.
The subscription's object has the following interface:
export interface OrganizationSubscription {
id: string;
priceId: string;
status: Stripe.Subscription.Status;
currency: string | null;
cancelAtPeriodEnd: boolean;
interval: string | null;
intervalCount: number | null;
createdAt: UnixTimestamp;
periodStartsAt: UnixTimestamp;
periodEndsAt: UnixTimestamp;
trialStartsAt: UnixTimestamp | null;
trialEndsAt: UnixTimestamp | null;
}
This interface is added to the Organization
object.
Subscription Updated
When a subscription is updated, we rebuild the subscription object and update it in the organization's Firestore entity.
Subscription Deleted
When a subscription is deleted, we simply remove it from the organization entity.
Adding additional webhooks
If you want to add additional webhooks, you can do so by adding a new case in the switch statement.
For example, if you want to handle the customer.subscription.trial_will_end
event, you can do so by adding the following case:
case 'customer.subscription.trial_will_end': {
// handle trial will end
}
Adding additional data to the subscription object
If you want to add additional data to the subscription object, you can do so by adding the data to the OrganizationSubscription
interface.
For example, if you want to add the quantity
property to the subscription object, you can do so by adding the following property to the interface:
export interface OrganizationSubscription {
// ...
quantity: number | null;
}
Then, you can add the data to the subscription object using the buildOrganizationSubscription
function:
import type { Stripe } from 'stripe';
import type { OrganizationSubscription } from '~/lib/organizations/types/organization-subscription';
export function buildOrganizationSubscription(
subscription: Stripe.Subscription,
): OrganizationSubscription {
const lineItem = subscription.items.data[0];
const price = lineItem.price;
return {
// your props
quantity: lineItem.quantity,
// default props
id: subscription.id,
priceId: price?.id,
status: subscription.status,
cancelAtPeriodEnd: subscription.cancel_at_period_end,
currency: lineItem.price.currency ?? null,
interval: price?.recurring?.interval ?? null,
intervalCount: price?.recurring?.interval_count ?? null,
createdAt: subscription.created,
periodStartsAt: subscription.current_period_start,
periodEndsAt: subscription.current_period_end,
trialStartsAt: subscription.trial_start ?? null,
trialEndsAt: subscription.trial_end ?? null,
};
}