Storing users in the convex database. Mutations vs webhooks?

[subtle furnace]

In this guide: https://docs.convex.dev/auth/database-auth it claims that only by using webhooks is it possible to store additional user information that isn't included in the JWT. This seems wrong to me. Why can I not simply add information to a user record created directly using a mutation after the fact?

[faint notch]

Hi @subtle furnace. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

You're right to question this, as the statement in the guide is not entirely accurate. Let me clarify this for you based on the information provided in the knowledge sources.

The guide you referenced does indeed suggest that only webhooks allow storing information not contained in the JWT. However, this is not strictly true. You can certainly store additional user information using mutations after the initial user creation.

Here's a more accurate breakdown:

1. Mutations: You can use mutations to store user information, including additional data not present in the JWT. The Auth > Storing Users in the Convex Database guide provides an example of a mutation that stores basic user information. You can extend this mutation or create additional mutations to store extra user data after the initial user creation.

2. Webhooks: These are useful for automatically syncing user data from your auth provider to Convex, especially when user information changes on the auth provider's side.

The key difference is not about what information you can store, but rather when and how you update that information:

• Mutations allow you to store and update user information on-demand, typically triggered by actions in your application.
• Webhooks automatically update user information when it changes in your auth provider, without requiring explicit action in your app.

You're correct that you can add information to a user record created directly using a mutation after the fact. This can be done through additional mutations that update the user record.

For example, the Auth > Advanced: Details > Writing additional data during authentication section shows how you can use the afterUserCreatedOrUpdated callback to write additional data during or after user creation:

export const { auth, signIn, signOut, store, isAuthenticated } = convexAuth({
  providers: [GitHub, Password],
  callbacks: {
    async afterUserCreatedOrUpdated(ctx: MutationCtx, { userId }) {
      await ctx.db.insert("someTable", { userId, data: "some data" });
    },
  },
});

This demonstrates that you can indeed add extra information to user records beyond what's in the JWT, using mutations or callbacks.

In conclusion, while the guide's statement is not entirely accurate, both mutations and webhooks have their place in managing user data in Convex, depending on your specific needs and workflow.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: