WorkOS is an auth service provider with a variety of products. It has an Events API which allows customers to sync WorkOS data within their application. WorkOS also provides webhooks but the Events API is the recommended approach to syncing data.
This repository contains a Cloudflare worker which runs on a schedule (every 60 seconds) and persists WorkOS data to a Cloudflare D1 database. You can still use this code with another SQL database by using Hyperdrive. As of now, this repository does not contain a Hyperdrive example.
- Have
npm,yarnorpnpminstalled. Commands in this repo usepnpm - Install dependencies via
pnpm i - Initialize the dev DB with
pnpm run dev:init-db - Start jaeger containers for viewing telemetry with
docker compose up -d - Go to http://localhost:16686 for the dev environment and http://localhost:16687 for the test environment to view traces
- Copy
sample.dev.varsto.dev.vars - Add your WorkOS credentials to the
.dev.varsfile - Run with
pnpm run dev - In another terminal tab run
curl 'http://localhost:8787/__scheduled?cron=*+*+*+*+*' - The default behavior for the development environment is to request events in the last 60 seconds from the WorkOS Events API
- You can modify this behavior by adding
EVENTS_RANGE_STARTand/orEVENTS_RANGE_ENDto.dev.varsto fetch events within a given time range. Both env vars need to be a Unix Timestamp in Milliseconds - See the Testing section for how to generate and test events within a specific time range
- This example worker does not take in event replay into account, processing the same event again will result in an error because the
event_idand payload will already be in the database. This can be viewed as a feature or a bug depending on how you look at it - Running newer events is considered safe but please do your own testing
- Create a new migration
pnpm run migrations:create kustom_app_dev create_user_org_cursor_tables --env dev
- Apply migrations
pnpm run dev:init-db
- Reset development DB
pnpm run dev:destroy-db
The current recommended approach for testing Cloudflare Workers is the Vitest Integration. It is in beta and I have not had a great experience with it, so far. The Vitest Integration is pinned to vitest version 1.5.0 at the time of writing (Sep 2024).
The tests in this repo DO NOT use the Vitest Integration. They run on the latest version of Vitest and Miniflare. The setup probably seems tedious but since I've invested the time and effort to get it working, I'm rolling with it until the Vitest Integration is stable.
I didn't want to create new events every time the test suite runs. To get around that, I create a set of events that are appropriate for my use case, then set the EVENTS_RANGE_START and EVENTS_RANGE_END environment variables for the test environment. This ensures that I'm always processing the same events but still calling out to the real WorkOS API.
Over time, when new events are added, they can be re-processed and the time interval for test events can be updated.
- To run the test suite, copy
sample.envrcto.envrcif you use direnv or ensure those env vars are loaded - The test suite uses Vitest and Node's
process.envto read environment variables - Uncomment the test at the top of
cursor.test.tsand run the suite withpnpm run test - The tests will fail since the IDs for each entity will be different compared to the ones I've used
- You can replace the IDs or change the
emitTestingEvents()function to match your use case - Once you've matched the IDs, the tests should pass
- If you want to examine your test D1 database, it's in
.wrangler/state/test/v3/d1/miniflare-D1DatabaseObject
The implementation in this repo was informed by this blog post from WorkOS.
Thanks for providing an alternative to the webhook strategy and writing a detailed post about it.
If you have questions or would like to chat about this implementation, feel free to reach out via email: hello@kustom.dev