
Designing a Stripe, Apple, and Google Play subscription event handler
When your user purchases or updates their subscription in your app, Stripe, Apple, or Google Play sends out an event that can be used to update your record of their subscription status. In my previous article, Building an open source subscription backend, I gave a high-level overview of building an open source, self-hostable service known as SubTru. SubTru processes the subscription events sent from Stripe, the Apple App Store, and Google Play and makes your users' subscription statuses available to your web or mobile app through a GET /access endpoint. In this article, I'll dive deeper into some of the design decisions I made when building SubTru.
System requirements#
Before jumping into design decisions, it helps to define the system requirements. In the case of SubTru, I wanted a service that could:
- Receive subscription events from Stripe, the Apple App Store, and Google Play
- Process those events and write subscription records to a database
- Make user subscription info available to an app for product access decisions
- Be easily self-hostable so it could be used by other developers
Designing the system#
The API#
I wanted this system to work with the three main providers (Stripe, the Apple App Store, and Google Play). Considering the requirements, it made sense to build part of this service as an API so it could both receive subscription events from these providers and make user subscription statuses available to your app through an HTTP endpoint. Here is a high-level overview of that design:

The processor#
After our system receives a subscription event, the next step would be to process it. This is where things started to get more interesting. Processing an event involves verifying the event actually came from Stripe, Apple, or Google Play, extracting the subscription data from the event (or fetching the subscription status in Google Play's case), storing the subscription data in a common model, ensuring the event is not a duplicate or stale, and responding back to the provider to indicate whether or not the event was successfully processed.
Service split#
Multiple services#

A very sensible architecture for this type of system would be to use a queue and split receiving and processing events into separate services. We could have the API receive events (and provide GET /access checks), a queue to hold events that have not yet been processed, and a worker service to handle processing the events at its own pace. If the processor can't process events as fast as the API receives them, a queue can absorb those bursts. This would allow the receiving and processing systems to scale independently. A queue could theoretically improve reliability by allowing us to store an event and process it at some point in the future, but this isn't as useful in our case since providers will redeliver events until we return a 200 response. The main drawback of adding a queue would be the extra complexity around maintenance and deployment. Since ease of self-hosting was a main requirement for this system, I still wanted to consider alternatives.
Single service#

To address the drawback of complexity, I wondered if it would make sense to combine receiving and processing events into a single service. In this design, the service would attempt to process the event right after receiving it. This would allow us to deploy everything from a single Docker image, greatly reducing complexity for self-hosters. Another advantage of this approach would be a faster update to a user's subscription status after receiving an event, since it wouldn't have to pass through a queue first. The main drawback of this approach is that coupling multiple systems (receiving requests, processing events, and providing access checks) means a performance bottleneck in one system could degrade performance in another since they could potentially be competing for the same resources like API or database CPU, memory, and connections. For example, heavy traffic on the GET /access endpoint could pull resources and connections that might slow down or prevent events from being received or processed. This can be mitigated by caching the response to reduce the number of calls and improving performance of the GET request itself. On the flip side, a burst in provider events could slow down access checks. Rate limiting or creating a smaller connection pool for incoming events could help with this. Another potential concern with this design is the lack of failure isolation. For example, a crash when processing a webhook event could also cause a separate part of the system (like access checks) to fail (that's another reason why caching access responses from your app is a good idea). Running multiple instances of the server is an easy way to keep the overall system resilient and mitigate problems if one instance goes down.
Middle ground#
There are plenty of other designs that land somewhere between the examples I gave above. For example, we could keep receiving and processing events together and run the GET /access checks on a separate deployment. We could do that with or without a queue. The queue could be a Postgres table or a service like SQS. I'm open to considering all designs, but until a need arises, I prefer to keep things as simple as possible. At the time of writing this, SubTru is using the single-service design, since it keeps things simpler, and no major performance concerns have been identified at the current scale. Performance testing the system would be a great next step to identify how excessive load in one area might slow things down in another. This performance data would be worth analyzing before adding complexity to the system unnecessarily.
Database#
The type of database in this system matters a lot less, since we just need the ability to store and read data. A NoSQL database could have worked perfectly fine, but I decided to use Postgres because a lot of the data we store is relational in nature. Postgres is also widely adopted by the open source community, so it felt like a great fit for that reason as well.
Deployment#
Self-hosting SubTru only requires you to deploy two things:
- A Postgres DB
- The SubTru service
Deploying the Postgres DB#
The SubTru service needs a Postgres database to work, so it's best to set this up first. Once you've created your database, you can run the DB migration scripts in the GitHub repo to create all the necessary tables.
Deploying the SubTru service#
The SubTru service can be deployed by building the image from the Dockerfile in the GitHub repo and then running it as a container wherever you prefer, as long as it can connect to your database and has a public HTTPS URL to receive provider events. You'll also need to set some secrets documented in the README.
Sequence diagrams#
Stripe / Apple#
Stripe and Apple webhook events both follow a very similar pattern for how they are processed.

Google#
Google Play sends real-time developer notifications (RTDNs) through Pub/Sub, and requires purchase acknowledgement through the Google Play Developer API.

Open source GitHub repo#
SubTru is open source under the Apache 2.0 license. All contributions are welcome. There is also a managed SubTru Cloud offering with a dashboard if you would prefer not to self-host.
Please consider giving SubTru a star on GitHub. I would really appreciate it.