Docs: Update data management docs

contents/docs/data/events.mdx

@@ -68,7 +68,7 @@ PotHog detects boolean values and allows filtering by only:
 
 ### Dates and Timestamps
 
-PostHog detects several formats of string as dates and times
+PostHog detects several formats of string as dates and times:
 
 -   YYYY-MM-DD,
 -   Date and date and time strings from [the ISO8601 standard](https://en.wikipedia.org/wiki/ISO_8601),
@@ -92,6 +92,8 @@ Filtering against that property will then show a date picker and allows filterin
 
 ![query list for a date time property lists only equals, before, after, is set, is not set](../../images/features/events/datetime-type-operators.png)
 
+> Read more about [how PostHog calculates timestamps](/docs/data/timestamps).
+
 ### Numeric
 
 PostHog detects numeric properties and allow filtering by only:

contents/docs/data/timestamps.md

@@ -0,0 +1,17 @@
+---
+title: Timestamps
+sidebar: Docs
+showTitle: true
+---
+
+PostHog automatically computes timestamps for captured events, but you can also set them manually. For example:
+
+- If the payload contains `timestamp` and `sent_at` fields, the `sent_at` field is compared to the server time to account for clock skew. The event's `timestamp` is adjusted by this difference before being stored. This is the method our libraries use.
+
+- If the payload includes a `timestamp` but no `sent_at` field, then `timestamp` is directly used as the event timestamp.
+
+- If `offset` is included in the payload, then this value is interpreted as milliseconds and is subtracted from the capture time recorded by the server to obtain the event timestamp. The first two alternatives have higher priority so `offset` is ignored if `timestamp` is present.
+
+- Finally, as a fallback when no `timestamp` or `offset` are included in the payload, the capture time recorded by the server is used as the event timestamp.
+
+To ensure maximum compatibility with PostHog, `timestamp` and `sent_at` fields should be in `ISO-8601` format like `2023-12-13T15:45:30.123Z` or `YYYY-MM-DDTHH:MM:SSZ`.

contents/tutorials/hogql-date-time-filters.md

@@ -23,7 +23,7 @@ HogQL filters are available on every type of insight from trends to funnels to l
 
 Below is a non-exhaustive list of time properties that are commonly used in HogQL (You can find a full list of events, properties, and types in your [data management tab](https://app.posthog.com/data-management/events)):
 
-- The `timestamp` property indicates what time an event occurred, and is automatically set.
+- The `timestamp` property indicates what time an event occurred, and is generally [automatically set](/docs/data/timestamps).
 - [Persons](/docs/data/persons) have a `created_at` property, which you can access with `person.created_at`.
 - For custom events or person properties, you can access them with `person.properties.{custom_property_name}`.
 

contents/tutorials/time-breakdowns.md

@@ -26,7 +26,7 @@ You can visualize this with a total value bar chart to the sums for the date ran
 
 ![Time of day](../images/tutorials/time-breakdowns/day.png)
 
-> **Note:** Event timestamps default to UTC. You need to adjust your times depending on your local time. For example, if you are in Pacific Daylight Time, subtract 7 hours from UTC timestamps to match your local time.
+> **Note:** Event [timestamps](/docs/data/timestamps) default to UTC. You need to adjust your times depending on your local time. For example, if you are in Pacific Daylight Time, subtract 7 hours from UTC timestamps to match your local time.
 
 ## Hourly breakdown
 

src/navs/index.js

@@ -1326,6 +1326,10 @@ export const docsMenu = {
                             name: 'Team collaboration',
                             url: '/docs/data/team-collaboration',
                         },
+                        {
+                            name: 'Timestamps',
+                            url: '/docs/data/timestamps',
+                        },
                         {
                             name: 'User properties',
                             url: '/docs/data/user-properties',