Clerk event: user.created, create the local record and never guess the primary email

user.created: create the local record

Fires once per user, when the user object is first created in Clerk. This is the moment to create your own user row keyed by the Clerk user id.

What to do on receipt

1. Take the Clerk id from evt.data.id. Store it as your external user key. It never changes for this user.
2. Find the primary email: read evt.data.primary_email_address_id, then pick the entry in evt.data.email_addresses whose id matches it. Do NOT assume email_addresses[0] is primary. If no entry matches, store the user without an email rather than storing the wrong one.
3. Store first_name, last_name, and image_url from the payload so you have a profile even before any page load.
4. Copy public_metadata into your record if you gate features on it. Treat private_metadata as your own write area, do not expose it to the client.
5. Return 200.

The trap

Guessing the primary email. Clerk orders email_addresses by recency of addition, not primacy. Agents that hardcode index 0 send welcome emails and receipts to a secondary address. The correct lookup is always primary_email_address_id first.

Checklist

• Upsert, never insert blind. Retried deliveries and replays will send this event twice.
• The payload is a snapshot at creation time. Later profile edits arrive as user.updated, so refresh on that event instead of caching this one forever.
• Return 200 only after your row exists. A 5xx tells Clerk to retry, which is safe only if step 1 is an upsert.

Clerk's syncing guide documents user.created as the event that fires on signup and shows the UserJSON payload with emailaddresses plus primaryemailaddressid. Verified live at https://clerk.com/docs/guides/development/webhooks/syncing. The verifyWebhook reference documents the evt.type/evt.data shape. Verified live at https://clerk.com/docs/reference/backend/verify-webhook.