SSO Data Sharer Webhook

Real-time information about SSO users can be pushed to a third party system via the data sharer webhooks described in this document.

Introduction

This service notifies an external third-party system about SSO users, sharing their profile and contact preferences. Third parties use it to ingest data about SSO users and keep it up to date. An update is sent whenever a user does something that changes their data, for example updating their first name or opting in or out of a contact method.

There are two webhooks, each a separate service you can subscribe to:

Service in CortexEventsPayload
Fan profileprofile.updated, profile.deletedThe full user profile, see Profile payload
Preferences centrepreferences.updatedThe user's preferences, see Preferences webhook

A client can subscribe to both, and can register more than one webhook for each.

Setting up a webhook

Webhooks are managed in Cortex under Settings → Webhooks. You need permission to manage webhooks.

  1. Select Add webhook.
  2. Choose the Service: Fan profile or Preferences centre.
  3. Choose the Events to receive.
  4. Enter the Webhook URL. It must be https:// if the key is sent in a header or the URL (see Authentication).
  5. Enter or generate a Secret of at least 16 characters. It signs every delivery. It is write-only: once saved, Cortex shows only Secret configured. If the secret is lost, set a new one and update your receiver.
  6. Choose the Payload version (see Model versions) and the delivery options below.
OptionApplies toDefaultWhat it does
Payload versionBothNone, requiredThe payload model version this webhook receives. Fan profile: 2 or 3. Preferences centre: 1.
Include secondary account linksFan profile, version 3OffAdds accountLinks.secondaryLinks to the payload
Key deliveryBothSignature onlySignature only, Signature and key in header (x-cortex-webhook-key), or Signature and key in URL (?key= plus the header). See Authentication.
Send the bare payloadBoth, with the key in a header or the URLOffSends the payload on its own, without the envelope. Use it to move an existing integration without changing the receiver.
Deliver to Azure Event HubsBothOffSee Azure Event Hubs

Webhooks can be switched off and on, edited and deleted from the same screen. A webhook must be switched off before it can be deleted.

📘

Existing integrations

Webhooks set up by the Cortex team before self-service keep working exactly as before: a bare payload with the key in the key query parameter and the x-cortex-webhook-key header. To move one to a self-service webhook without changing the receiver, choose Signature and key in URL and Send the bare payload, with the same secret.

Delivery format

Each delivery is an HTTP POST to the webhook URL with Content-Type: application/json.

Example requests

How the request looks for a webhook URL of https://example.com/webhook and a secret of PzRt3Fs5cvs8P2pAqegwJk5VZtYJ0IDk, for each key delivery:

Key deliveryMethodURLHeaders
Signature only (default)POSThttps://example.com/webhookX-Cortex-Signature: t=2026-11-10T12:00:00Z,sha256=5f2b...e91c
Signature and key in headerPOSThttps://example.com/webhookX-Cortex-Signature: t=...,sha256=...
x-cortex-webhook-key: PzRt3Fs5cvs8P2pAqegwJk5VZtYJ0IDk
Signature and key in URLPOSThttps://example.com/webhook?key=PzRt3Fs5cvs8P2pAqegwJk5VZtYJ0IDkX-Cortex-Signature: t=...,sha256=...
x-cortex-webhook-key: PzRt3Fs5cvs8P2pAqegwJk5VZtYJ0IDk
Existing integration set up by the Cortex team (legacy)POSThttps://example.com/webhook?key=PzRt3Fs5cvs8P2pAqegwJk5VZtYJ0IDkx-cortex-webhook-key: PzRt3Fs5cvs8P2pAqegwJk5VZtYJ0IDk

The key in the URL and the x-cortex-webhook-key header are still supported, for existing integrations and for receivers that can't verify a signature. See Authentication. Legacy integrations set up by the Cortex team receive the bare payload, without the X-Cortex-Signature header.

Envelope or bare payload

The request body is in one of two shapes. Which one you get depends only on how the webhook is set up:

Webhook setupBody
Send the bare payload off, and Deliver to Azure Event Hubs off (the default)Envelope: the payload is inside data
Send the bare payload onBare payload: the payload on its own
Deliver to Azure Event Hubs onBare payload: the payload on its own
Existing integration set up by the Cortex team (legacy)Bare payload: the payload on its own

The payload itself (the profile payload or the preferences payload) is identical in both shapes. The envelope only wraps it.

With the envelope (default)

{
  "id": "0b6f3f8e-5c1d-4a9e-9a57-3f2a6d0f9c41",
  "event": "profile.updated",
  "timestamp": "2026-11-10T12:00:00Z",
  "data": {
    "id": 6688176,
    "version": 3,
    "recordRevoked": false,
    "clientId": "CLIENT",
    "registerMetadata": { "registerSource": "XX", "registerType": "XX", "registerPlatform": "XX" },
    "userProfile": { "id": 6688176, "email": "[email protected]", "firstName": "Jane", "lastName": "Doe" },
    "clientPreferences": [],
    "entitlements": [],
    "accountLinks": []
  }
}
FieldTypeDefinition
idString (UUID)Identifies the delivery. It is the same on every retry of that delivery, so use it to discard duplicates.
eventStringThe event: profile.updated, profile.deleted or preferences.updated
timestampString, RFC 3339 UTC, secondsWhen the delivery was signed. Equal to t= in the signature header.
dataObjectThe payload, for the webhook's payload version

Without the envelope (bare payload)

The same delivery, with Send the bare payload or Deliver to Azure Event Hubs on. The body is exactly what was inside data above:

{
  "id": 6688176,
  "version": 3,
  "recordRevoked": false,
  "clientId": "CLIENT",
  "registerMetadata": { "registerSource": "XX", "registerType": "XX", "registerPlatform": "XX" },
  "userProfile": { "id": 6688176, "email": "[email protected]", "firstName": "Jane", "lastName": "Doe" },
  "clientPreferences": [],
  "entitlements": [],
  "accountLinks": []
}

Without the envelope there is no delivery id, event or timestamp in the body:

  • Tell a deleted user from an update by recordRevoked: true (the profile.deleted event).
  • The X-Cortex-Signature header is still sent on self-service webhooks and still covers the whole body, so verification works the same way.
  • See Responses, retries and ordering for handling duplicates without the delivery id.

profile.deleted is sent when the user has asked for their account to be deleted. Its payload has recordRevoked: true.

Authentication

Signature (always sent)

Every delivery carries an X-Cortex-Signature header:

X-Cortex-Signature: t=2026-11-10T12:00:00Z,sha256=5f2b...e91c

sha256 is the hex-encoded HMAC-SHA256 of t + "." + body, keyed with the webhook's secret. body is the raw request body exactly as received. To verify a delivery:

  1. Split the header into t and sha256.
  2. Compute HMAC-SHA256(secret, t + . + raw body) and hex-encode it.
  3. Compare it with sha256 using a constant-time comparison.
  4. Reject the delivery if t is more than 5 minutes from your current time. This guards against replays. Each retry is signed again, so retries pass this check.

Verify against the raw bytes received, before parsing the JSON. Re-serialising the JSON changes the bytes and the signature will not match.

Node.js

const crypto = require('crypto');

function verifyCortexWebhook(secret, header, rawBody, toleranceSeconds = 300) {
  const match = /^t=([^,]+),sha256=([0-9a-f]+)$/.exec(header || '');
  if (!match) return false;
  const [, t, received] = match;

  const expected = crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex');
  if (expected.length !== received.length ||
      !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) return false;

  return Math.abs(Date.now() - Date.parse(t)) / 1000 <= toleranceSeconds;
}

Python

import hashlib, hmac, re
from datetime import datetime, timezone

def verify_cortex_webhook(secret: str, header: str, raw_body: bytes, tolerance_seconds: int = 300) -> bool:
    match = re.fullmatch(r"t=([^,]+),sha256=([0-9a-f]+)", header or "")
    if not match:
        return False
    t, received = match.groups()

    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, received):
        return False

    signed_at = datetime.fromisoformat(t.replace("Z", "+00:00"))
    return abs((datetime.now(timezone.utc) - signed_at).total_seconds()) <= tolerance_seconds

Key in a header or the URL (optional)

For receivers that can't verify a signature, the webhook can also send the secret itself:

Key deliveryAlso sends
Signature only (default)Nothing else
Signature and key in headerx-cortex-webhook-key: <secret>
Signature and key in URL?key=<secret> on the URL, and the x-cortex-webhook-key header

These modes require an https:// URL. A key in the URL can end up in proxy and server access logs, so prefer the signature, or the header if you need a key.

Azure Event Hubs

What is Azure Event Hubs?

Azure Event Hubs is Microsoft's managed event-streaming service. Instead of running your own web server to receive webhooks, you have the updates written straight into an event hub in your own Azure subscription. Your systems then read them from there, at their own pace:

  • Your own consumers: read the events with the Event Hubs SDKs or the Kafka protocol.
  • Azure services: Stream Analytics, Azure Functions, Microsoft Fabric and others can read from an event hub directly.
  • Archiving: Event Hubs Capture can archive every event to Azure Storage or Data Lake.

This suits clients who already use Azure for their data platform. Events are kept in the hub for its retention period, so a consumer that is down catches up when it comes back instead of missing deliveries.

The terms used below:

TermMeaning
NamespaceThe container for one or more event hubs, with its own host name: <namespace>.servicebus.windows.net
Event hubThe stream the events are written to, inside a namespace
Shared access policyA named key with rights (Send, Listen, Manage). Cortex uses a policy's name and key to sign each request with a shared access signature (SAS)

See Event Hubs features and terminology for more.

Setting up Azure

  1. Namespace. Create an Event Hubs namespace in the Azure portal, or use an existing one.
  2. Event hubs. Create one event hub per webhook, e.g. cortex-sso-profiles for the Fan profile webhook and cortex-preferences for the Preferences centre webhook. The two payloads have different shapes, so keeping them in separate hubs means each consumer reads one format. Choose the partition count and retention to suit your consumers. Retention is how long events stay readable if a consumer is down.
  3. Shared access policy. On each event hub (not the namespace), open Settings → Shared access policies and add a policy with only the Send claim, e.g. cortex-send. You can use the same policy name on every hub. Each hub's policy has its own keys, so each key can only send to its own hub.
  4. Key. Copy each policy's Primary key. See Get an Event Hubs connection string for where to find it. You only need the key, not the full connection string. You end up with one key per event hub, and so one per webhook in Cortex.
  5. Consumers. Read the events with the Event Hubs SDKs, the Kafka protocol, or an Azure service such as Stream Analytics or Functions. Use your own consumer group for each reader.
📘

Least privilege

Cortex only needs Send on the one event hub each webhook delivers to. Never give Cortex the namespace's RootManageSharedAccessKey or any policy with Listen or Manage rights: those keys can read, and with Manage delete, your event hubs.

A Send-only policy on the namespace also works, but its key can send to every event hub in the namespace. Prefer one policy per event hub. See Shared access signature authorization for Event Hubs.

Network restrictions. If the namespace limits public network access (IP firewall rules or private endpoints only), deliveries from Cortex are blocked. Ask the Cortex team for the outbound IP addresses to allow.

Event size. Each delivery is one event. Event Hubs limits an event to 256 KB on the Basic tier and 1 MB on Standard and above. Profile payloads are typically a few KB, growing with the number of preferences and account links.

Setting up the webhook in Cortex

Tick Deliver to Azure Event Hubs and fill in:

  • Webhook URL: the event hub's REST endpoint, https://<namespace>.servicebus.windows.net/<event-hub>/messages. This is the Send event endpoint. The host must end in .servicebus.windows.net.
  • Shared access policy name: the name of the policy on this webhook's event hub, from step 3, e.g. cortex-send.
  • Shared access policy key: that policy's key, from step 4. Use the key from the same event hub as the URL: a key from another hub's policy is rejected with 401. For an Event Hubs webhook, this key is the webhook's secret, and there is no separate secret to set.
  • Token lifetime (seconds): optional. The default is 86400 (24 hours) and the maximum is 31536000 (one year). Cortex generates a new token before the old one expires, so the lifetime only limits how long a single intercepted token stays valid.

Rotating the key

Each policy has a primary and a secondary key, so you can rotate without missing deliveries:

  1. Update the webhook in Cortex to use the policy's secondary key.
  2. Regenerate the primary key in Azure.
  3. Next time, switch back the other way.

Regenerating a key invalidates the tokens made from it straight away. If you regenerate the key Cortex is using before updating the webhook, deliveries fail with 401 and are retried for a limited time.

What is sent

  • Authorization: each request carries an Authorization: SharedAccessSignature sr=...&sig=...&se=...&skn=... header. It is a SAS token generated from the policy name and key.
  • Event body: the bare payload, with no envelope. Each delivery becomes one event in the hub.
  • Event properties: Event Hubs stores custom request headers as the event's user (application) properties. So each event also carries the X-Cortex-Signature header, signed with the policy key, which you can verify as described in Signature.
  • Not used: key delivery and Send the bare payload don't apply.
  • Failures and retries: Event Hubs answers 201 Created on success. Any other response, e.g. 401 for a wrong key or policy name, is treated as a failure and retried like any other webhook delivery.

Turning Event Hubs on or off in Cortex clears the secret, so the policy key is never reused as a webhook secret or the other way round.

Responses, retries and ordering

  • Success: respond with any 2xx status within 30 seconds. The response body is ignored.
  • Retries: a timeout, a connection error, a 5xx or any other non-2xx response counts as a failure.
    • Connection errors and 5xx responses are retried immediately, up to 3 times.
    • After that, the delivery is retried every 5 minutes, a limited number of times, then dropped.
  • Duplicates: deliveries are at least once. Use the envelope id to discard duplicates. With the bare payload there is no envelope id, so make processing idempotent on the user ID and userProfile.lastUpdated, or createdAt for preferences.
  • Ordering: deliveries are not guaranteed to arrive in order. Use userProfile.lastUpdated (profile) or createdAt (preferences) to ignore an update older than one you already have.
  • Redirects: followed only to the same host, including from http to https. A redirect to another host is not followed and counts as a failure, so the secret is never sent to a host you didn't configure.
  • Changes take effect quickly: switching a webhook off, deleting it or changing its secret applies within about 30 seconds to deliveries not yet sent, including retries already queued.

Profile payload

This is the payload of the Fan profile webhook: the envelope's data, or the whole body for a bare payload or Event Hubs. Every delivery contains the full user profile, regardless of what changed.

FieldTypeDefinition
idNumberThe user's unique SSO ID
versionNumberThe payload model version. It is the version the webhook is pinned to in Cortex (see Model versions).
recordRevokedBooleanTrue if the user has asked for their account to be deleted under GDPR. Sent with the profile.deleted event. You must either delete the user record from your system or remove all PII associated with this user's SSO ID.
clientIdStringThe ID associated with this client e.g. CORTEX
registerMetadata.registerSourceStringThe source location the user first registered
registerMetadata.registerTypeStringThe type of registration
registerMetadata.registerPlatformStringThe platform the user registered on
userProfile.idNumberThe user's unique SSO ID
userProfile.emailStringThe user's email address
userProfile.emailVerifiedBooleanTrue if the user's email is verified - false otherwise
userProfile.guardianEmailStringThe email address of their guardian if the user is a minor
userProfile.minorIdStringIf the user is a minor this is their username/nickname
userProfile.firstNameStringThe user's first name
userProfile.otherNamesStringThe user's middle name
userProfile.lastNameStringThe user's last name
userProfile.titleStringThe user's title, e.g. Mr, Mrs, Dr
userProfile.birthDateISO 8601 DatetimeThe user's date of birth
userProfile.genderStringThe user's gender. Based on RFC 6350: M = Male, F = Female, O = Other, N = None or not applicable, U = Unknown
userProfile.address1StringThe user's address line 1
userProfile.address2StringThe user's address line 2
userProfile.townStringThe user's town
userProfile.regionStringThe user's region / county
userProfile.countryStringThe user's country
userProfile.postcodeStringThe user's postcode
userProfile.contactNumberStringThe user's phone number
userProfile.screenNameStringThe user's screen name / display name
userProfile.screenNameApprovedBooleanTrue if the user's screen name has been approved through moderation
userProfile.profilePictureStringURL to the user's profile picture
userProfile.profilePictureApprovedBooleanTrue if the user's profile picture has been approved through moderation
userProfile.companyNameStringThe user's company name
userProfile.companyPhoneNumberStringThe user's company phone number
userProfile.companyAddressOneStringThe user's company address line 1
userProfile.companyAddressTwoStringThe user's company address line 2
userProfile.companyTownStringThe user's company town
userProfile.companyCountryStringThe user's company country
userProfile.companyPostcodeStringThe user's company postcode
userProfile.lastUpdatedISO 8601 DatetimeThe last time the user updated their profile information
userProfile.createdAtISO 8601 DatetimeThe date and time the user created their SSO account
userProfile.metadataJSONUnstructured JSON object that contains additional information about the user, for example: "metadata": { "object": {}, "key": "value", "number": 1, "array": [1, "value"], "boolean": false }
userProfile.suspensionObjectIf the user's account has been suspended this field will contain information about it. If the user is not suspended then this field will be null.
userProfile.suspension.typeStringThe type of account suspension
userProfile.suspension.expiresAtISO 8601 DatetimeThe date and time this suspension will elapse. If null this account is suspended indefinitely.
userProfile.suspension.reasonStringA free text field providing additional context for suspension reason. This field can be null.
userProfile.passwordResetBooleanTrue if the user has reset their password. This field may be absent if no password reset has occurred.
userProfile.lastPasswordResetISO 8601 DatetimeThe date and time of the user's most recent password reset. Only present if a password reset has occurred.
userProfile.firstLoginISO 8601 DatetimeThe date and time the user first logged in
userProfile.lastLoginISO 8601 DatetimeThe date and time the user most recently logged in
clientPreferencesArrayThis contains the list of account preferences available to the user
clientPreferences.clientIdStringThe ID associated with this client i.e. CORTEX
clientPreferences.nameStringThe display name of the preference
clientPreferences.descriptionStringThe description of the preference
clientPreferences.keyStringThe unique key for this preference. Note: this is unique per client ID, not per user.
clientPreferences.setBooleanIf true this indicates that the user has responded to this preference. This is useful for some preferences where the user is not obliged to select an option i.e. a checkbox preference. In this case we know the user has acknowledged the preference but not chosen any options.
clientPreferences.optionsArrayA list of options available to the user for this preference
clientPreferences.options.idNumberThe globally unique ID of this option
clientPreferences.options.valueStringThe display text for this option
clientPreferences.options.metadataObjectKey / value pairs of additional metadata associated with this option. Both keys and values are strings.
clientPreferences.options.selectedBooleanTrue if the user has selected this option - false otherwise
entitlementsArrayA list of active entitlements this user has. Expired entitlements are excluded. Version 3 only — this field is not present in version 2 payloads.
entitlements.idStringThe ID of this entitlement
entitlements.nameStringThe name of this entitlement
entitlements.validFromISO 8601 DatetimeThe date and time this entitlement is valid from
entitlements.validToISO 8601 DatetimeThe date and time this entitlement is valid to. This will be null for entitlements that are open ended or never expire i.e. a lifetime membership or staff entitlement.
accountLinksArrayA list of account IDs linked to this SSO account. Version 3 only — this field is not present in version 2 payloads.
accountLinks.sourceSystemIdStringThe system this account link relates to e.g. cortex_VM for Ticketmaster
accountLinks.sourceSystemUserIdStringThe ID of the user's account within that system
accountLinks.sourceSystemCreatedAtISO 8601 DatetimeThe date and time this account link was created at the source, i.e. at Ticketmaster.
accountLinks.createdAtISO 8601 DatetimeThe date and time this account link was created
accountLinks.lastModifiedISO 8601 DatetimeThe date and time this account link was last updated
accountLinks.primaryBooleanTrue if this is the primary account link for this source system
accountLinks.secondaryLinksArrayA list of secondary account links associated with this primary link. Each entry has the same structure as an accountLink. Only present when Include secondary account links is turned on for the webhook (payload version 3).

Model versions

A webhook receives exactly the payload version chosen for it in Cortex. It is never moved to a newer version automatically, so a new version can't change what your receiver gets until you choose it. New webhooks should use the latest version.

Version 2 includes: id, version, recordRevoked, clientId, registerMetadata, userProfile, and clientPreferences.

Version 3 includes everything in Version 2, plus:

  • entitlements — the user's active entitlements

  • accountLinks — external accounts linked to this SSO account (with optional secondary links)

The preferences webhook has one payload version, 1.

Example (version 3):

{
  "id": 6688176,
  "version": 3,
  "clientId": "CLIENT",
  "registerMetadata": {
    "registerSource": "XX",
    "registerType": "XX",
    "registerPlatform": "XX"
  },
  "entitlements": [
    {
      "id": "68623c8e5fab911b5396d1a9",
      "name": "pre season bundle 2026",
      "validFrom": "2026-03-18T17:51:20Z",
      "validTo": "2026-03-31T10:00:00Z"
    }
  ],
  "accountLinks": [
    {
      "sourceSystemId": "System4",
      "sourceSystemUserId": "fTVOpxDMyUmOwVXXX",
      "createdAt": "2021-06-20T15:29:57.58203Z",
      "lastModified": "2021-06-20T15:29:57.58203Z"
    },
    {
      "sourceSystemId": "XXXX_SG",
      "sourceSystemUserId": "718863",
      "createdAt": "2023-06-23T10:00:33.115011Z",
      "lastModified": "2023-06-23T10:00:33.115011Z"
    },
    {
      "sourceSystemId": "YYYY_VM",
      "sourceSystemUserId": "718863",
      "sourceSystemCreatedAt": "2024-12-03T09:09:27.445024Z",
      "createdAt": "2023-06-29T15:02:19.905433Z",
      "lastModified": "2024-12-03T09:09:27.463658Z"
    }
  ],
  "clientPreferences": [
    {
      "clientId": "CLIENT",
      "name": "Highlights, news, and videos",
      "description": "Send me the latest news and videos from the club, including transfers and match highlights",
      "set": true,
      "key": "001-highlights-news-videos",
      "options": [
        {
          "id": 958,
          "value": "Yes",
          "metadata": {
            "hidden": "false",
            "order": "1",
            "type": "opt-in",
            "visualType": "radio"
          },
          "selected": false
        },
        {
          "id": 959,
          "value": "No",
          "metadata": {
            "hidden": "false",
            "order": "2",
            "type": "opt-in",
            "visualType": "radio"
          },
          "selected": false
        }
      ]
    },
    {
      "clientId": "CLIENT",
      "name": "Tickets and Memberships",
      "description": "Send me ticket announcements and availability, Memberships, and Season Ticket information",
      "set": true,
      "key": "002-tickets-memberships",
      "options": [
        {
          "id": 960,
          "value": "Yes",
          "metadata": {
            "hidden": "false",
            "order": "1",
            "type": "opt-in",
            "visualType": "radio"
          },
          "selected": false
        },
        {
          "id": 961,
          "value": "No",
          "metadata": {
            "hidden": "false",
            "order": "2",
            "type": "opt-in",
            "visualType": "radio"
          },
          "selected": false
        }
      ]
    },
    {
      "clientId": "CLIENT",
      "name": "Club Shop",
      "description": "Send me the latest from the club shop",
      "set": true,
      "key": "003-club-shop",
      "options": [
        {
          "id": 962,
          "value": "Yes",
          "metadata": {
            "hidden": "false",
            "order": "1",
            "type": "opt-in",
            "visualType": "radio"
          },
          "selected": false
        },
        {
          "id": 963,
          "value": "No",
          "metadata": {
            "hidden": "false",
            "order": "2",
            "type": "opt-in",
            "visualType": "radio"
          },
          "selected": false
        }
      ]
    },
    {
      "clientId": "CLIENT",
      "name": "Premium Hospitality and commercial opportunities",
      "description": "Send me Premium hospitality news and offers, and commercial opportunities",
      "set": true,
      "key": "004-premium-hospitality-commercial",
      "options": [
        {
          "id": 964,
          "value": "Yes",
          "metadata": {
            "hidden": "false",
            "order": "1",
            "type": "opt-in",
            "visualType": "radio"
          },
          "selected": false
        },
        {
          "id": 965,
          "value": "No",
          "metadata": {
            "hidden": "false",
            "order": "2",
            "type": "opt-in",
            "visualType": "radio"
          },
          "selected": false
        }
      ]
    },
    {
      "clientId": "CLIENT",
      "name": "Venue hire and events",
      "description": "Send me club events and venue hire communications",
      "set": true,
      "key": "005-venue-hire-events",
      "options": [
        {
          "id": 966,
          "value": "Yes",
          "metadata": {
            "hidden": "false",
            "order": "1",
            "type": "opt-in",
            "visualType": "radio"
          },
          "selected": false
        },
        {
          "id": 967,
          "value": "No",
          "metadata": {
            "hidden": "false",
            "order": "2",
            "type": "opt-in",
            "visualType": "radio"
          },
          "selected": false
        }
      ]
    },
    {
      "clientId": "CLIENT",
      "name": "Partners and sponsors",
      "description": "Send me news and promotions from club partners",
      "set": true,
      "key": "006-partners-sponsors",
      "options": [
        {
          "id": 968,
          "value": "Yes",
          "metadata": {
            "hidden": "false",
            "order": "1",
            "type": "opt-in",
            "visualType": "radio"
          },
          "selected": false
        },
        {
          "id": 969,
          "value": "No",
          "metadata": {
            "hidden": "false",
            "order": "2",
            "type": "opt-in",
            "visualType": "radio"
          },
          "selected": false
        }
      ]
    },
    {
      "clientId": "CLIENT",
      "name": "Club Foundation",
      "description": "Send me the latest news and updates from the club foundation",
      "set": true,
      "key": "007-club-foundation",
      "options": [
        {
          "id": 970,
          "value": "Yes",
          "metadata": {
            "hidden": "false",
            "order": "1",
            "type": "opt-in",
            "visualType": "radio"
          },
          "selected": false
        },
        {
          "id": 971,
          "value": "No",
          "metadata": {
            "hidden": "false",
            "order": "2",
            "type": "opt-in",
            "visualType": "radio"
          },
          "selected": false
        }
      ]
    },
    {
      "clientId": "CLIENT",
      "name": "Women's Team",
      "description": "Send me the latest news and updates from the women's team",
      "set": true,
      "key": "008-womens-team",
      "options": [
        {
          "id": 972,
          "value": "Yes",
          "metadata": {
            "hidden": "false",
            "order": "1",
            "type": "opt-in",
            "visualType": "radio"
          },
          "selected": false
        },
        {
          "id": 973,
          "value": "No",
          "metadata": {
            "hidden": "false",
            "order": "2",
            "type": "opt-in",
            "visualType": "radio"
          },
          "selected": false
        }
      ]
    },
    {
      "clientId": "CLIENT",
      "name": "I am also happy to hear from the Club via SMS",
      "set": true,
      "key": "009-other-contact-methods-sms",
      "options": [
        {
          "id": 974,
          "value": "Yes",
          "metadata": {
            "hidden": "false",
            "order": "1",
            "type": "opt-in",
            "visualType": "radio"
          },
          "selected": false
        },
        {
          "id": 975,
          "value": "No",
          "metadata": {
            "hidden": "false",
            "order": "2",
            "type": "opt-in",
            "visualType": "radio"
          },
          "selected": false
        }
      ]
    }
  ],
  "userProfile": {
    "id": 6688176,
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "birthDate": "1988-01-01T00:00:00Z",
    "gender": "F",
    "address1": "1 Example Street",
    "address2": "Line 2",
    "town": "Exampletown",
    "region": "Example County",
    "country": "United Kingdom",
    "postcode": "AB1 2CD",
    "contactNumber": "07700900000",
    "lastUpdated": "2026-03-18T17:51:52.4Z",
    "metadata": {},
    "createdAt": "2021-06-20T12:12:08.178Z",
    "passwordReset": true,
    "lastPasswordReset": "2026-03-03T14:25:51.557038Z",
    "firstLogin": "2021-06-29T11:14:07.162229Z",
    "lastLogin": "2026-03-18T17:41:28.364391Z"
  }
}

Preferences webhook

In addition to the profile webhook described above, the data sharer supports a separate preferences webhook. This is a dedicated channel for receiving real-time preference change notifications with a richer preference data model.

The preferences webhook fires whenever a user updates their preference selections (e.g. opting in or out of a contact method, changing a preference option). It sends the preferences.updated event.

It covers anonymous users as well as SSO users: someone who sets their preferences through the preferences centre without an SSO account is sent with anonymous: true (see the anonymous user example). The profile webhook only covers SSO users, so anonymous preferences are only available from the preferences webhook.

Choose the Preferences centre service in Cortex to set it up. It is delivered, signed and retried exactly like the profile webhook. A client can receive both.

The profile webhook described above includes a clientPreferences section with basic preference data. The preferences webhook provides a richer, dedicated preference payload with additional fields.

CapabilityProfile WebhookPreferences Webhook
Triggered byAny SSO profile updatePreference selection changes only
Preference key & nameYesYes
Option id, value, selectedYesYes
Preference descriptionNoYes
Preference type (OptIn, Global)NoYes
Visual type (Radio, Checkbox, Select)NoYes
Preference deprecated flagNoYes
Last updated timestampNoYes
Option index (display ordering)NoYes
Option metadata (key/value pairs)NoYes
Option linked IDs (external system refs)NoYes
Option deprecated flagNoYes
Anonymous (non-SSO) usersNoYes (anonymous: true)
User profile data (name, address, etc.)Yes (full profile)No
EntitlementsYes (v3 only)No
Account linksYes (v3 only)No

Example payloads

These are the envelope's data for the preferences.updated event, or the whole body for a bare payload or Event Hubs.

Anonymous user

{
  "clientId": "CLIENT",
  "userId": 27146712,
  "anonymous": true,
  "email": "[email protected]",
  "uuid": "8b4d1f52-6499-41e2-a6f4-26d8616988df",
  "preferences": [
    {
      "key": "001-highlights-news-videos",
      "name": "Highlights, news, and videos",
      "description": "Send me the latest news and videos from the club, including transfers and match highlights",
      "set": false,
      "type": "OptIn",
      "visualType": "Radio",
      "deprecated": false,
      "lastUpdated": null,
      "options": [
        {
          "id": 958,
          "index": 1,
          "value": "Yes",
          "metadata": {},
          "linkedIds": [],
          "selected": false,
          "deprecated": false
        },
        {
          "id": 959,
          "index": 2,
          "value": "No",
          "metadata": {},
          "linkedIds": [],
          "selected": false,
          "deprecated": false
        }
      ]
    },
    {
      "key": "002-tickets-memberships",
      "name": "Tickets and Memberships",
      "description": "Send me ticket announcements and availability, Memberships, and Season Ticket information",
      "set": false,
      "type": "OptIn",
      "visualType": "Radio",
      "deprecated": false,
      "lastUpdated": null,
      "options": [
        {
          "id": 960,
          "index": 1,
          "value": "Yes",
          "metadata": {},
          "linkedIds": [],
          "selected": false,
          "deprecated": false
        },
        {
          "id": 961,
          "index": 2,
          "value": "No",
          "metadata": {},
          "linkedIds": [],
          "selected": false,
          "deprecated": false
        }
      ]
    },
    {
      "key": "003-club-shop",
      "name": "Club Shop",
      "description": "Send me the latest from the club shop",
      "set": false,
      "type": "OptIn",
      "visualType": "Radio",
      "deprecated": false,
      "lastUpdated": null,
      "options": [
        {
          "id": 962,
          "index": 1,
          "value": "Yes",
          "metadata": {},
          "linkedIds": [],
          "selected": false,
          "deprecated": false
        },
        {
          "id": 963,
          "index": 2,
          "value": "No",
          "metadata": {},
          "linkedIds": [],
          "selected": false,
          "deprecated": false
        }
      ]
    }
  ],
  "version": 1,
  "createdAt": "2026-03-18T17:41:02.949459786Z"
}

Real SSO user

{
  "clientId": "CLIENT",
  "userId": 6688176,
  "anonymous": false,
  "email": "[email protected]",
  "uuid": "1ed05d06-c7e2-4637-a184-1fd0073b7727",
  "preferences": [
    {
      "key": "001-highlights-news-videos",
      "name": "Highlights, news, and videos",
      "description": "Send me the latest news and videos from the club, including transfers and match highlights",
      "set": true,
      "type": "OptIn",
      "visualType": "Radio",
      "deprecated": false,
      "lastUpdated": "2026-03-18T17:41:48.769214Z",
      "options": [
        {
          "id": 958,
          "index": 1,
          "value": "Yes",
          "metadata": {},
          "linkedIds": [],
          "selected": false,
          "deprecated": false
        },
        {
          "id": 959,
          "index": 2,
          "value": "No",
          "metadata": {},
          "linkedIds": [],
          "selected": true,
          "deprecated": false
        }
      ]
    },
    {
      "key": "002-tickets-memberships",
      "name": "Tickets and Memberships",
      "description": "Send me ticket announcements and availability, Memberships, and Season Ticket information",
      "set": true,
      "type": "OptIn",
      "visualType": "Radio",
      "deprecated": false,
      "lastUpdated": "2026-03-18T17:41:48.769214Z",
      "options": [
        {
          "id": 960,
          "index": 1,
          "value": "Yes",
          "metadata": {},
          "linkedIds": [],
          "selected": false,
          "deprecated": false
        },
        {
          "id": 961,
          "index": 2,
          "value": "No",
          "metadata": {},
          "linkedIds": [],
          "selected": true,
          "deprecated": false
        }
      ]
    },
    {
      "key": "003-club-shop",
      "name": "Club Shop",
      "description": "Send me the latest from the club shop",
      "set": true,
      "type": "OptIn",
      "visualType": "Radio",
      "deprecated": false,
      "lastUpdated": "2026-03-18T17:41:48.769214Z",
      "options": [
        {
          "id": 962,
          "index": 1,
          "value": "Yes",
          "metadata": {},
          "linkedIds": [],
          "selected": false,
          "deprecated": false
        },
        {
          "id": 963,
          "index": 2,
          "value": "No",
          "metadata": {},
          "linkedIds": [],
          "selected": true,
          "deprecated": false
        }
      ]
    }
  ],
  "version": 1,
  "createdAt": "2026-03-18T17:41:48.805845172Z"
}

Payload fields

FieldTypeRequiredDefinition
clientIdStringYesThe ID associated with this client
userIdNumberYesThe user's unique SSO ID
anonymousBooleanYesWhether this is an anonymous user
emailStringYesThe user's email address
minorIdStringOptionalIf the user is a minor, this is their username/nickname
guardianEmailStringOptionalThe email address of their guardian if the user is a minor
uuidStringYesA unique identifier for this user's account
versionNumberYesThe payload version. Always 1.
createdAtISO 8601 DatetimeYesThe timestamp of this webhook event
preferencesArrayYesThe user's current preference selections
preferences.keyStringYesThe unique key identifying this preference
preferences.nameStringYesThe display name of the preference
preferences.descriptionStringOptionalA description of the preference
preferences.setBooleanOptionalTrue if the user has responded to this preference, even if no options were selected. May be null.
preferences.typeStringOptionalThe preference classification, e.g. OptIn, Global. May be null.
preferences.visualTypeStringYesThe UI display type: Radio, Checkbox, or Select
preferences.deprecatedBooleanYesTrue if this preference has been deprecated
preferences.lastUpdatedISO 8601 DatetimeOptionalThe last time this specific preference was updated. May be null.
preferences.optionsArrayYesThe available options for this preference
preferences.options.idNumberYesThe globally unique ID of this option
preferences.options.indexNumberYesThe display order index for this option
preferences.options.valueStringYesThe display text for this option
preferences.options.metadataObjectYesKey / value pairs of additional metadata associated with this option
preferences.options.linkedIdsArrayYesExternal system references linked to this option (e.g. OPTA football team IDs)
preferences.options.linkedIds.textStringOptionalDisplay text for this linked ID. May be null.
preferences.options.linkedIds.sourceSystemStringYesThe external system this ID relates to
preferences.options.linkedIds.sourceSystemIdStringYesThe ID within that external system
preferences.options.selectedBooleanOptionalTrue if the user has selected this option. May be null.
preferences.options.deprecatedBooleanYesTrue if this option has been deprecated

Which webhook should I use?

  • Use the profile webhook if you need the full user profile (name, email, address, etc.) alongside basic preference data, entitlements, and account links.
  • Use the preferences webhook if you need detailed, real-time preference change data with enriched metadata (type, visual type, option metadata, linked IDs, deprecation flags), or the preferences of anonymous users who don't have an SSO account.
  • You can subscribe to both, for example the profile webhook for identity data and the preferences webhook for consent changes.

Did this page help you?