Why doesn't user.update.complete fire when email verification changes verified flag?
-
When using FusionAuth's email verification flow, the
verifiedflag inuser.datachanges, but theuser.update.completewebhook event does not fire.We sync user state to external systems through the Kafka integration (using Azure Event Hub's Kafka endpoints). We expected
user.update.completeto fire for all user mutations, including when theverifiedflag changes during the email verification process.Without this event firing, we have to listen to both
user.update.completeanduser.email.verifiedevents. However, since both events contain theverifiedflag on theuserobject and can fire simultaneously, this creates race conditions downstream — the Kafka integration doesn't guarantee ordering unless the partitioning strategy is keyed on userId.Why doesn't
user.update.completefire when email verification changes the verified state? Is there a recommended approach to handle this scenario without encountering race conditions? -
The
user.update.completeevent intentionally does not fire when theverifiedflag changes through email verification. This is by design.Email verification is considered a distinct workflow separate from the general user update process in FusionAuth's event model. As noted in a related GitHub issue, the decision was made to introduce dedicated verification events rather than triggering
user.update.completebecause email verification "does not occur due to the Update User API, but because of a separate workflow." Theuser.update.completeevent is reserved for changes made through the Update User API, while verification-specific changes trigger their own dedicated events.Recommended Solution
You should listen to these specific webhook events for verification state changes:
user.email.verified— fires when an email address is verified (available since 1.8.0)user.identity.verified— fires when an identity (email or phone number) is verified (available since 1.59.0)
Handling Race Conditions
If you're concerned about race conditions when multiple events fire simultaneously:
- Adjust your Kafka partitioning strategy to key on
userId— this ensures all events for the same user go to the same partition and are processed in order - Use event timestamps in your downstream consumers to deduplicate or order events correctly. Each event includes a
createInstantfield in the event object that can be used for ordering - Design your sync logic to be idempotent so that processing events out of order doesn't cause inconsistent state
The separate
user.email.verifiedanduser.identity.verifiedevents provide more granular control over what verification changes you respond to, which is generally more useful than a generic user update event.Related Documentation
- User Update Complete Event — documentation for the
user.update.completeevent - User Email Verified Event — documentation for the
user.email.verifiedevent - User Identity Verified Event — documentation for the
user.identity.verifiedevent - Kafka Integration — comprehensive guide to FusionAuth's Kafka integration for consuming webhook events
- Webhook Event Log — review events sent by FusionAuth with timing and result information
-
D dan has marked this topic as solved