UID2-7488: clarify opt-out webhook timestamp unit (Unix seconds)

[sunnywu]

What

Clarifies the unit of the timestamp parameter in the opt-out webhook table in the DSP integration guide → Honor user opt-outs. The table previously said only "The time when the user opted out (for information only)" with no unit.

Changes:

• State that timestamp is a Unix timestamp in seconds.
• Add a :::note distinguishing it from POST /optout/status's opted_out_since, which is in milliseconds.

Why

A DSP integrating the opt-out webhook could not tell whether the value was Unix seconds or milliseconds. The ambiguity is real because the sibling /optout/status endpoint returns milliseconds, so a reader could reasonably assume the webhook matches — it does not.

Source of truth (verified in code)

The webhook value is Unix epoch seconds:

• IABTechLab/uid2-optout OptOutPartnerEndpoint.java substitutes the ${OPTOUT_EPOCH} macro (the guide's %%timestamp%%) directly with String.valueOf(entry.timestamp) — no conversion.
• IABTechLab/uid2-shared OptOutEntry.java documents the entry's timestamp field as 7 bytes -- timestamp (seconds); uid2-optout OptOutServiceVerticle.java writes OptOutUtils.nowEpochSeconds() = Instant.now().getEpochSecond().
• Contrast: IABTechLab/uid2-operator UIDOperatorVerticle.java builds the /optout/status response via Instant.ofEpochSecond(timestamp).toEpochMilli() — deliberately milliseconds.

Jira

https://thetradedesk.atlassian.net/browse/UID2-7488

🤖 Generated with Claude Code

[UID2SourceAdmin]

🤖 AI Code Review

Generated by Azure OpenAI (gpt-5). Automated — human review is still required.

Summary

This PR clarifies the opt-out webhook documentation by explicitly stating that the webhook timestamp is a Unix timestamp in seconds, and contrasts it with the opted_out_since field from POST /optout/status, which uses milliseconds.

Strengths

• Good documentation improvement on a subtle but important contract detail: calling out seconds vs. milliseconds reduces integration errors for DSPs.
• The added note makes the discrepancy easy to spot at the point of use, rather than forcing readers to infer it from separate endpoint docs.
• The glossary link for “Unix timestamp” improves precision without overloading the table entry.

Findings

No issues found in the diff provided.

Verdict

Ready to merge? Yes

Reasoning: This is a clear, targeted docs fix that improves consumer understanding of an existing wire-format detail without introducing code or contract changes.