Skip to content

feat(webhooks): define persistent multiaccount identity and member deltas #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
KonstantinSerebryakov merged 2 commits into from
Oct 7, 2026
Merged

feat(webhooks): define persistent multiaccount identity and member deltas #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6bc3466
fix(webhooks): enforce multiaccount transition ancestry
KonstantinSerebryakov Oct 7, 2026
29ca11c
feat(webhooks): define persistent cluster identity and membership deltas
KonstantinSerebryakov Oct 7, 2026
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
50 changes: 49 additions & 1 deletion dist/schemas/multiaccount-changed-event.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,8 @@
"revision",
"previous_revision",
"user_hids",
"added_user_hids",
"removed_user_hids",
"users_count",
"members_complete",
"evaluated_at",
Expand Down Expand Up @@ -95,7 +97,7 @@
"cluster_id": {
"type": "string",
"format": "uuid",
"description": "ID of the exact sorted user set within this site. A membership change resolves the old group and detects a new group."
"description": "Persistent site-qualified group identity. Unambiguous expansion or contraction preserves this ID; ambiguous split/merge starts new identities."
},
"revision": {
"type": "string",
Expand Down Expand Up @@ -128,6 +130,24 @@
}
}
},
"added_user_hids": {
"type": "array",
"uniqueItems": true,
"description": "Sorted members added since the previous transition; all current members for detected.",
"items": {
"type": "string",
"minLength": 1
}
},
"removed_user_hids": {
"type": "array",
"uniqueItems": true,
"description": "Sorted members removed since the previous transition; all previous members for resolved.",
"items": {
"type": "string",
"minLength": 1
}
},
"users_count": {
"type": "integer",
"minimum": 3,
Expand Down Expand Up @@ -198,6 +218,34 @@
}
},
"allOf": [
{
"if": {
"properties": {
"action": {
"const": "detected"
}
},
"required": [
"action"
]
},
"then": {
"additionalProperties": true,
"properties": {
"previous_revision": {
"type": "null"
}
}
},
"else": {
"additionalProperties": true,
"properties": {
"previous_revision": {
"type": "string"
}
}
}
},
{
"if": {
"properties": {
Expand Down
50 changes: 49 additions & 1 deletion dist/schemas/webhook-event.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -880,6 +880,8 @@
"revision",
"previous_revision",
"user_hids",
"added_user_hids",
"removed_user_hids",
"users_count",
"members_complete",
"evaluated_at",
Expand Down Expand Up @@ -924,7 +926,7 @@
"cluster_id": {
"type": "string",
"format": "uuid",
"description": "ID of the exact sorted user set within this site. A membership change resolves the old group and detects a new group."
"description": "Persistent site-qualified group identity. Unambiguous expansion or contraction preserves this ID; ambiguous split/merge starts new identities."
},
"revision": {
"type": "string",
Expand Down Expand Up @@ -957,6 +959,24 @@
}
}
},
"added_user_hids": {
"type": "array",
"uniqueItems": true,
"description": "Sorted members added since the previous transition; all current members for detected.",
"items": {
"type": "string",
"minLength": 1
}
},
"removed_user_hids": {
"type": "array",
"uniqueItems": true,
"description": "Sorted members removed since the previous transition; all previous members for resolved.",
"items": {
"type": "string",
"minLength": 1
}
},
"users_count": {
"type": "integer",
"minimum": 3,
Expand Down Expand Up @@ -1027,6 +1047,34 @@
}
},
"allOf": [
{
"if": {
"properties": {
"action": {
"const": "detected"
}
},
"required": [
"action"
]
},
"then": {
"additionalProperties": true,
"properties": {
"previous_revision": {
"type": "null"
}
}
},
"else": {
"additionalProperties": true,
"properties": {
"previous_revision": {
"type": "string"
}
}
}
},
{
"if": {
"properties": {
Expand Down
78 changes: 70 additions & 8 deletions dist/shieldlabs-api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -439,7 +439,7 @@
"Webhooks"
],
"summary": "A multi-account group changed",
"description": "Opt-in notification when a complete background detector publication detects, updates, or\nresolves an exact group of accounts. Enable `multiaccount: true` on the webhook endpoint.\nThe default is false; existing identification.scored subscriptions are preserved.\n\nA repeated build with unchanged membership, level, and rules does not produce a new event.\nA membership change produces resolved for the previous exact group and detected for the new\nexact group. Resolved means the group is no longer supported by the current complete source\ncut, including evidence expiry; it does not certify that its accounts are safe.\n\nDelivery is at least once, with no global ordering guarantee. Save event_id atomically with\nyour business operation. Within a site, publication epoch, and cluster_id, compare revision\nas an integer and ignore older transitions. Verify HMAC-SHA256 over the raw received bytes;\nX-Shield-Event-Id is a convenience header, and the signed body is authoritative.\n\nThis event has no request_id or risk_score. Its source identifies the published group result;\nit does not mutate an earlier identification.scored body or an already pinned Console view.",
"description": "Opt-in notification when a complete background detector publication detects, updates, or\nresolves an exact group of accounts. Enable `multiaccount: true` on the webhook endpoint.\nThe default is false; existing identification.scored subscriptions are preserved.\n\nA repeated build with unchanged membership, level, and rules does not produce a new event.\nAn unambiguous membership expansion or contraction preserves cluster_id and produces updated.\nAmbiguous splits or merges resolve replaced groups and detect new identities. Resolved means the group is no longer supported by the current complete source\ncut, including evidence expiry; it does not certify that its accounts are safe.\n\nDelivery is at least once, with no global ordering guarantee. Save event_id atomically with\nyour business operation. Within a site, publication epoch, and cluster_id, compare revision\nas an integer and ignore older transitions. Verify HMAC-SHA256 over the raw received bytes;\nX-Shield-Event-Id is a convenience header, and the signed body is authoritative.\n\nThis event has no request_id or risk_score. Its source identifies the published group result;\nit does not mutate an earlier identification.scored body or an already pinned Console view.",
"security": [],
"parameters": [
{
Expand Down Expand Up @@ -2039,6 +2039,8 @@
"revision",
"previous_revision",
"user_hids",
"added_user_hids",
"removed_user_hids",
"users_count",
"members_complete",
"evaluated_at",
Expand Down Expand Up @@ -2083,7 +2085,7 @@
"cluster_id": {
"type": "string",
"format": "uuid",
"description": "ID of the exact sorted user set within this site. A membership change resolves the old group and detects a new group."
"description": "Persistent site-qualified group identity. Unambiguous expansion or contraction preserves this ID; ambiguous split/merge starts new identities."
},
"revision": {
"type": "string",
Expand Down Expand Up @@ -2116,6 +2118,24 @@
}
}
},
"added_user_hids": {
"type": "array",
"uniqueItems": true,
"description": "Sorted members added since the previous transition; all current members for detected.",
"items": {
"type": "string",
"minLength": 1
}
},
"removed_user_hids": {
"type": "array",
"uniqueItems": true,
"description": "Sorted members removed since the previous transition; all previous members for resolved.",
"items": {
"type": "string",
"minLength": 1
}
},
"users_count": {
"type": "integer",
"minimum": 3,
Expand Down Expand Up @@ -2186,6 +2206,34 @@
}
},
"allOf": [
{
"if": {
"properties": {
"action": {
"const": "detected"
}
},
"required": [
"action"
]
},
"then": {
"additionalProperties": true,
"properties": {
"previous_revision": {
"type": "null"
}
}
},
"else": {
"additionalProperties": true,
"properties": {
"previous_revision": {
"type": "string"
}
}
}
},
{
"if": {
"properties": {
Expand Down Expand Up @@ -3436,7 +3484,7 @@
"summary": "Multi-account group detected",
"description": "Generated by the Core event marshaler for a synthetic three-account group.",
"value": {
"event_id": "ad5efdbb113f50d1207c3a3b1d03e54ee60dfb9a",
"event_id": "7795f86574643ece49997885d0a0a3e5768dcb74",
"site_id": 319,
"event_type": "hre.multi_account.changed",
"schema_version": "2026-10-07",
Expand All @@ -3448,9 +3496,15 @@
"status": "evaluated",
"detected": true,
"level": "medium",
"cluster_id": "4293f02e-7cf0-5cda-9150-b5b8c4ee685d",
"cluster_id": "abc35eb1-2cd7-5c28-a805-f3b7c1682a2f",
"revision": "7412",
"previous_revision": null,
"added_user_hids": [
"account_a",
"account_b",
"account_c"
],
"removed_user_hids": [],
"user_hids": [
"account_a",
"account_b",
Expand Down Expand Up @@ -3481,7 +3535,7 @@
"summary": "Multi-account group updated",
"description": "Generated by the Core event marshaler for a synthetic three-account group.",
"value": {
"event_id": "27225e88895f45c6f96562578308d3afea9d4ea2",
"event_id": "2feaa43f05ad19dadd78c85c465c8b4d101f9e2f",
"site_id": 319,
"event_type": "hre.multi_account.changed",
"schema_version": "2026-10-07",
Expand All @@ -3493,9 +3547,11 @@
"status": "evaluated",
"detected": true,
"level": "high",
"cluster_id": "4293f02e-7cf0-5cda-9150-b5b8c4ee685d",
"cluster_id": "abc35eb1-2cd7-5c28-a805-f3b7c1682a2f",
"revision": "7414",
"previous_revision": "7412",
"added_user_hids": [],
"removed_user_hids": [],
"user_hids": [
"account_a",
"account_b",
Expand Down Expand Up @@ -3526,7 +3582,7 @@
"summary": "Multi-account group resolved",
"description": "Generated by the Core event marshaler for a synthetic three-account group.",
"value": {
"event_id": "0e703af70ff450065df0457d71789d32df4de079",
"event_id": "1f12f427edb3e4b74df2c0c958db49186ef0a7b9",
"site_id": 319,
"event_type": "hre.multi_account.changed",
"schema_version": "2026-10-07",
Expand All @@ -3538,9 +3594,15 @@
"status": "evaluated",
"detected": false,
"level": null,
"cluster_id": "4293f02e-7cf0-5cda-9150-b5b8c4ee685d",
"cluster_id": "abc35eb1-2cd7-5c28-a805-f3b7c1682a2f",
"revision": "7415",
"previous_revision": "7412",
"added_user_hids": [],
"removed_user_hids": [
"account_a",
"account_b",
"account_c"
],
"user_hids": [
"account_a",
"account_b",
Expand Down
Loading
Loading