DEV Community

Cover image for Clerk webhook replay can create duplicate users unless your sync is idempotent
FetchSandbox
FetchSandbox

Posted on

Clerk webhook replay can create duplicate users unless your sync is idempotent

#clerk #webhooks #auth #webdev

The login worked. The webhook worked. Then the same event arrived again.

Clerk webhooks are easy to treat like a notification:

user.created arrived
create a local user
done
Enter fullscreen mode Exit fullscreen mode

That works until the event is retried, replayed, or delivered after another part of your app already created the user.

Then your app has two local rows for the same Clerk user. Or one row has the right email and the other has the right metadata. Or your onboarding job runs twice and sends the same welcome email twice.

The bug is not "Clerk webhooks are unreliable." Retrying delivery is normal webhook behavior.

The bug is trusting delivery count instead of provider state.

The narrow fix

Your webhook handler should not mean:

on user.created -> insert user
Enter fullscreen mode Exit fullscreen mode

It should mean:

on user.created -> upsert by clerk_user_id
Enter fullscreen mode Exit fullscreen mode

The important field is the stable provider ID, not the local row ID and not the email address.

await db.user.upsert({
  where: { clerkUserId: event.data.id },
  update: {
    email: event.data.email_addresses?.[0]?.email_address,
    firstName: event.data.first_name,
    lastName: event.data.last_name,
    clerkUpdatedAt: new Date(event.data.updated_at),
  },
  create: {
    clerkUserId: event.data.id,
    email: event.data.email_addresses?.[0]?.email_address,
    firstName: event.data.first_name,
    lastName: event.data.last_name,
    clerkUpdatedAt: new Date(event.data.updated_at),
  },
});
Enter fullscreen mode Exit fullscreen mode

That one constraint does most of the work:

UNIQUE(clerk_user_id)
Enter fullscreen mode Exit fullscreen mode

Now a replay updates the same user instead of creating a second one.

The part people skip

The handler can still be wrong even after the upsert.

If your app grants access, creates a workspace, starts a trial, or sends email inside the same handler, those side effects need their own idempotency rule too.

For example:

workspace owner = clerk_user_id
welcome email key = clerk_event_id
trial grant key = clerk_user_id + plan_id
Enter fullscreen mode Exit fullscreen mode

The user row is only one piece of local state.

How I would test it

I would test the same user.created event twice.

First delivery:

local user count: 0 -> 1
workspace count: 0 -> 1
Enter fullscreen mode Exit fullscreen mode

Replay:

local user count: 1 -> 1
workspace count: 1 -> 1
Enter fullscreen mode Exit fullscreen mode

That is the whole test.

FetchSandbox has a Clerk sandbox and runnable Clerk workflow docs for this exact kind of replay check. It is also where a stateful sandbox is more useful than a static mock response: the second delivery is the thing you need to observe.

Takeaway

Do not write Clerk webhook handlers as if events happen once.

Write them as reconciliation:

given this Clerk user ID,
what should my app state be now?
Enter fullscreen mode Exit fullscreen mode

If the answer changes when the same event arrives twice, the bug is already there. Production is just waiting to replay it.

Top comments (0)