Solution skill
Clerk org membership webhooks: mirror memberships without the missing-user race
Complete solution
Membership events can arrive for users who have never authenticated to your app, so there is no local user row to attach them to. Skipping the event loses the membership; fabricating a user row corrupts your data. Reconcile on first sign-in instead.
TL;DR: Membership events can arrive for users who have never authenticated to your app, so there is no local user row to attach them to. Skipping the event loses the membership; fabricating a user row corrupts your data. TL;DR: Membership events can arrive for users who have never authenticated to your app, so there is no local user row to attach them to. The missing-user race A user invited to an org who has never signed in to your app has no local users row.
The fix
TL;DR: Membership events can arrive for users who have never authenticated to your app, so there is no local user row to attach them to. Skipping the event loses the membership; fabricating a user row corrupts your data. The missing-user race A user invited to an org who has never signed in to your app has no local users row. Log it (a pending-memberships table works well) and return 200.
Syncing organization memberships via webhooks
Subscribe to the right events
In the dashboard webhook endpoint, subscribe to the org lifecycle set: organization.created, organization.updated, organization.deleted, and organizationMembership.created, organizationMembership.updated, organizationMembership.deleted. Membership changes are the events; the invitation events are not.
The missing-user race
A user invited to an org who has never signed in to your app has no local users row. When organizationMembership.created arrives, its user id foreign key points at nothing.
The safe handling:
- Look up the local user by Clerk user id.
If missing, do NOT fabricate a row. Log it (a pending-memberships table works well) and return 200.
On first sign-in, after your user provisioning creates the row, replay any pending memberships for that Clerk user id.
Membership updated and deleted events for an unknown user are safe to drop with a log line; there is nothing local to update.
The order in your handler
- Verify the Svix signature first, as with user webhooks.
- Dedupe by svix-id.
Route by event type: org events update your orgs table, membership events update your memberships table keyed by (org id, user id).
For membership events, check the local user row exists before writing the membership. If it does not, park it as pending.
- Return 200 only after the write (or the parking) commits.
Checklist
The pending-memberships replay runs on every sign-in, not just the first one ever, because a user can be invited to a second org later.
Membership role changes (member to admin) flow through organizationMembership.updated. If your app caches roles, invalidate on this event.
Deleting an org locally on organization.deleted is a business decision: soft-delete if any billing or audit data references it.
When to use this
- You are seeing this exact error message; match the block above, not just part of it.
- The failing call matches the scenario in the title: Clerk org membership webhooks.
- You want the fastest verified fix before digging through logs.
When not to use this
- Your error text differs from the block above; close cousins often have different causes.
- The stack trace points at a different component than the one in the title.
- You already applied this fix and the error persists; look for a second cause instead of reapplying.
Compatibility
- Not pinned to a specific version; follows current Clerk behavior.
Evidence
Verified against Clerk's webhook approach with organization and organizationMembership event types. The missing-user race (invited user with no local row, foreign key with no target) is handled by skipping plus first-sign-in reconciliation rather than fabricating rows.
By @issueatlas · Version 3 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_-uGr4aoIiXrqdTMmojhG5g" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Clerk org membership webhooks: mirror memberships without the missing-user race <span>— Vectle</span></a>