Create PostHog Event Naming Rules
Name events around stable product actions and document when they fire. A useful convention is a shared contract across engineering and analysis, not a cosmetic rename of inconsistent instrumentation.
Before you start: Have the existing event inventory, key reports and an engineering owner. Preserve raw event names until a migration plan accounts for their consumers.
Worked example: Use report_created for a confirmed creation and report_create_failed for failure, with a documented reason category. Do not use one event name for both button intent and completed persistence.
Step-by-step guide
Inventory current meanings
List important event names and their firing conditions. Identify names that mix attempts, success and failure under one label.
Choose a consistent structure
Agree a readable object/action convention and a casing rule. Optimize for shared understanding rather than enforcing style while leaving semantics ambiguous.
Define required properties
Record the contextual fields needed to interpret each event. Keep stable identifiers separate from display names and avoid collecting unnecessary sensitive content.
Specify the trigger
Describe the exact product state that emits the event and who owns it. Test retries and background jobs so a user action does not generate unexplained duplicates.
Plan consumer migration
Find dashboards, actions and experiments that depend on renamed events. Use a deliberate transition rather than silently editing the meaning of an established metric.
Review after deployment
Check sample journeys and compare expected volumes. Update the definition with coverage dates and leave an owner responsible for future changes.
Common mistakes
Name standard without semantics
Consistent casing cannot fix conflicting triggers. Define the completed action.
Silent rename
Reports may lose continuity. Map consumers before deployment.
Too much content in properties
Names and identifiers often suffice. Do not capture private documents merely for convenience.
Tips
Use examples of valid and invalid payloads in the contract.
Give each core event one accountable owner.
Review the naming contract when a workflow changes.
Sources and verification
Based on product documentation checked on 2026-10-24. This is a documentation-based guide, not a hands-on benchmark. Features and availability can change.