Clerk session teardown events: ended vs removed vs revoked, they are not the same

TL;DR

Update your local session record to ended and move on. 2. session.removed: Clerk cleaned the session up, typically because the owning user was deleted or the client was removed. Switch on evt.type and record the terminal state with the specific reason. On session.ended and session.removed, just mark your record terminal.

When to use

You are seeing this: All three mean the session is over. Use this skill when you run into "Clerk session teardown events: ended vs removed vs revoked, they are not the same".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

All three mean the session is over. They differ in who ended it and what you should do about it.

What each means

1. session.ended: the session reached its natural end. The user signed out, or the session expired. This is the normal case. Update your local session record to ended and move on.
2. session.removed: Clerk cleaned the session up, typically because the owning user was deleted or the client was removed. The session is gone as a side effect. Treat it like ended for your records, but do not notify the user; there is no user to notify.
3. session.revoked: someone with authority killed this session: an admin revoke, a Backend API revoke call, or a security-triggered revoke. Treat this as a forced logout and a potential security event.

What to do on receipt

1. Switch on evt.type and record the terminal state with the specific reason. Your audit log should distinguish "user signed out" from "admin revoked."
2. On session.revoked, invalidate anything you derived from that session: cached permissions, issued tokens, "remember this device" flags. Then check whether the revoke was expected (your own admin action) or a surprise.
3. On session.ended and session.removed, just mark your record terminal. No notifications, no alarms.
4. Return 200.

The trap

Lumping them into one "session over" handler with identical behavior. Then a real revocation, the one case that needs action, gets the same shrug as a natural expiry. The event name IS the severity signal.

Checklist

• If you revoke sessions via the Backend API yourself, expect the matching session.revoked webhook. Make your handler idempotent to your own actions.
• user.deleted often arrives near session.removed for the same user. Handle both independently; either order must leave you clean.
• Never email the user about session.removed. The account behind it is usually gone.

Clerk's event catalog (Dashboard → Webhooks → Event Catalog) lists session.ended, session.removed, and session.revoked as distinct session events. The overview guide documents the webhook event model. Verified live at https://clerk.com/docs/guides/development/webhooks/overview.