Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,20 @@
# Changelog

## Unreleased

- `Event.getProjectId()` returns the Fingerly project an event belongs to, on
single reads and list rows. It is null when the server does not send it.
- Webhook `data` for `identification.completed` and `visitor.suspect` (and
`identification.refused` when the key was known) carries `project_id`; read
it from `getData()`.
- Events carry `ip_network` (`getIpNetwork()`), an IPv4 /24 or IPv6 /40,
instead of `ip_address`; the API no longer returns the address.
- `getDeferredSignals()` is removed: single-event reads no longer return the
deferred report.
- `getDocument()` is an allow-listed view of the archived submission, without
raw signals, user agent or address.
- The vendored contract snapshot is refreshed.

## 0.1.0

First release: event reads, webhook verification and the same-origin proxy,
Expand Down
10 changes: 9 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,9 @@ before network access, by `build()` rather than by the first call. Requests do
not follow redirects. `get` and `list` each perform one request and never
retry. A null, empty, `.` or `..` request id is an `IllegalArgumentException`.

`getProjectId()` is the UUID of the Fingerly project the event belongs to, on
`get` and on every `list` row; it is null when an older server does not send it.

## Artifacts

Java has no single HTTP server standard, so the proxy ships an adapter per
Expand Down Expand Up @@ -186,6 +189,8 @@ Apply your own policy to the server's verdict. A pending event
verify asynchronously, rather than refusing the action. Do not authorize an action using
scores or visitor identifiers supplied by the browser. Tags correlate events;
they do not replace your application's authentication or replay protection.
Never put a personal identifier (user ID, email, install ID or advertising ID)
in a tag: the server keeps tags in long-lived rollups.

## Webhooks

Expand All @@ -205,7 +210,10 @@ matching signature in the comma-separated header is accepted; at most 32 are
read. Malformed or missing input is a false result, never an exception.

`WebhookEvent.getData()` stays a `JsonNode`, so a new event type needs no SDK
upgrade; `getDataJson()` is the same as text.
upgrade; `getDataJson()` is the same as text. `identification.completed` and
`visitor.suspect` carry the event's project as `data.project_id`;
`identification.refused` carries it only when the refused request named a known
key. Read it with `getData().path("project_id")`.

## Same-origin proxy

Expand Down
43 changes: 17 additions & 26 deletions contract/fixtures.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,15 @@
{
"body": {
"request_id": "0199a963-e400-7000-8000-000000000001",
"project_id": "0199a963-e400-7000-8000-0000000000a1",
"visitor_id": "visitor-test",
"occurred_at": "2026-09-17T12:00:00Z",
"state": "enriched",
"environment": "development",
"platform": "web",
"sdk_platform": "web",
"sdk_version": "0.1.0",
"ip_address": "203.0.113.10",
"ip_network": "203.0.113.0/24",
"suspect_score": 0,
"suspect_level": "low",
"triggers": [],
Expand All @@ -23,14 +24,15 @@
{
"body": {
"request_id": "0199a963-e400-7000-8000-000000000001",
"project_id": "0199a963-e400-7000-8000-0000000000a1",
"visitor_id": "visitor-test",
"occurred_at": "2026-09-17T12:00:00Z",
"state": "unavailable",
"environment": "development",
"platform": "web",
"sdk_platform": "web",
"sdk_version": "0.1.0",
"ip_address": "203.0.113.10",
"ip_network": "203.0.113.0/24",
"suspect_score": null,
"triggers": [],
"has_document": false
Expand All @@ -42,14 +44,15 @@
{
"body": {
"request_id": "0199a963-e400-7000-8000-000000000001",
"project_id": "0199a963-e400-7000-8000-0000000000a1",
"visitor_id": "visitor-test",
"occurred_at": "2026-09-17T12:00:00Z",
"state": "enriched",
"environment": "development",
"platform": "web",
"sdk_platform": "web",
"sdk_version": "0.1.0",
"ip_address": "203.0.113.10",
"ip_network": "203.0.113.0/24",
"suspect_score": 0,
"suspect_level": "low",
"triggers": [],
Expand All @@ -58,24 +61,11 @@
"schema": 1,
"request_id": "0199a963-e400-7000-8000-000000000001",
"occurred_at": "2026-09-17T12:00:00Z",
"organization_id": "tenant-test",
"project_id": "",
"sdk_key_id": "",
"environment": "development",
"sdk": {
"platform": "",
"version": ""
},
"client_ip": "203.0.113.10",
"signals": null
},
"deferred_signals": {
"fonts": {
"status": "ok",
"value": [
"Arial"
]
}
"ip_network": "203.0.113.0/24"
}
},
"name": "archived",
Expand All @@ -87,14 +77,15 @@
"rows": [
{
"request_id": "0199a963-e400-7000-8000-000000000001",
"project_id": "0199a963-e400-7000-8000-0000000000a1",
"visitor_id": "visitor-test",
"occurred_at": "2026-09-17T12:00:00Z",
"state": "enriched",
"environment": "development",
"platform": "web",
"sdk_platform": "web",
"sdk_version": "0.1.0",
"ip_address": "203.0.113.10",
"ip_network": "203.0.113.0/24",
"suspect_score": 0,
"suspect_level": "low",
"triggers": [],
Expand Down Expand Up @@ -203,33 +194,33 @@
"webhooks": [
{
"name": "current",
"payload": "{\"id\":\"evt_contract\",\"type\":\"identification.completed\",\"data\":{\"request_id\":\"0199a963-e400-7000-8000-000000000001\"}}",
"payload": "{\"id\":\"evt_contract\",\"type\":\"identification.completed\",\"data\":{\"request_id\":\"0199a963-e400-7000-8000-000000000001\",\"project_id\":\"0199a963-e400-7000-8000-0000000000a1\"}}",
"secret": "whsec_contract_current",
"signature": "sha256=f222a3199dae906df4608030c73d742410e40f003bd7b25292db11edb306b9d4",
"signature": "sha256=cba83ffd4a95e203b68a3ca967fde148975766425da50f6d5f8dc973994823e5",
"timestamp": "1789646400",
"valid": true
},
{
"name": "rotation_current",
"payload": "{\"id\":\"evt_contract\",\"type\":\"identification.completed\",\"data\":{\"request_id\":\"0199a963-e400-7000-8000-000000000001\"}}",
"payload": "{\"id\":\"evt_contract\",\"type\":\"identification.completed\",\"data\":{\"request_id\":\"0199a963-e400-7000-8000-000000000001\",\"project_id\":\"0199a963-e400-7000-8000-0000000000a1\"}}",
"secret": "whsec_contract_current",
"signature": "sha256=f222a3199dae906df4608030c73d742410e40f003bd7b25292db11edb306b9d4,sha256=4d373c753341ff05adb96484a1ff629204fffb1889582a7ac905d61c60de35b5",
"signature": "sha256=cba83ffd4a95e203b68a3ca967fde148975766425da50f6d5f8dc973994823e5,sha256=ca64b6fb3b42c701bb03d7394d8a2111bfb4b3d364de1fa24ee3edd59e59bbd5",
"timestamp": "1789646400",
"valid": true
},
{
"name": "rotation_previous",
"payload": "{\"id\":\"evt_contract\",\"type\":\"identification.completed\",\"data\":{\"request_id\":\"0199a963-e400-7000-8000-000000000001\"}}",
"payload": "{\"id\":\"evt_contract\",\"type\":\"identification.completed\",\"data\":{\"request_id\":\"0199a963-e400-7000-8000-000000000001\",\"project_id\":\"0199a963-e400-7000-8000-0000000000a1\"}}",
"secret": "whsec_contract_previous",
"signature": "sha256=f222a3199dae906df4608030c73d742410e40f003bd7b25292db11edb306b9d4,sha256=4d373c753341ff05adb96484a1ff629204fffb1889582a7ac905d61c60de35b5",
"signature": "sha256=cba83ffd4a95e203b68a3ca967fde148975766425da50f6d5f8dc973994823e5,sha256=ca64b6fb3b42c701bb03d7394d8a2111bfb4b3d364de1fa24ee3edd59e59bbd5",
"timestamp": "1789646400",
"valid": true
},
{
"name": "tampered",
"payload": "{\"id\":\"evt_contract\",\"type\":\"identification.completed\",\"data\":{\"request_id\":\"0199a963-e400-7000-8000-000000000001\"}} ",
"payload": "{\"id\":\"evt_contract\",\"type\":\"identification.completed\",\"data\":{\"request_id\":\"0199a963-e400-7000-8000-000000000001\",\"project_id\":\"0199a963-e400-7000-8000-0000000000a1\"}} ",
"secret": "whsec_contract_current",
"signature": "sha256=f222a3199dae906df4608030c73d742410e40f003bd7b25292db11edb306b9d4",
"signature": "sha256=cba83ffd4a95e203b68a3ca967fde148975766425da50f6d5f8dc973994823e5",
"timestamp": "1789646400",
"valid": false
}
Expand Down
6 changes: 3 additions & 3 deletions contract/manifest.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
{
"schema": 1,
"serverCommit": "0c3fcf69928a3b75847d73203b1c881d14011e4c",
"serverCommit": "e22f96777b0d029464baa4e127d7a346b684d478",
"files": {
"openapi.json": "36430ff82eec2126879ede24bd175ec0ba40e4547a50a7b0530bd2dd4ee9e711",
"fixtures.json": "379517de50da86ac559c6b0a4c47f4959fd35bc0e31538329cc66331ded1ea8e"
"openapi.json": "850e7627dbbf1789fe7a0a214ae28838f2cd80d42e251f9994f5cb42d72e6009",
"fixtures.json": "3fbf2efbcf3c8ebced3d2c9f2a3c1f5752ee94ece63d5c110291d9a8251ff68f"
}
}
Loading
Loading