Webhooks

Audience webhooks push CDP events to your HTTPS endpoint as they happen—account links, and additional event types as the catalog grows. Delivery is a signed HTTP POST you configure once in Hub; new event types reuse the same envelope and verification flow.

How delivery works

You register an endpoint in Hub under Settings → Webhooks.
Immutable sends each event as a signed SNS notification to that URL.
Your server verifies the signature, acknowledges with 200, and handles the payload asynchronously.

All Audience webhook types share the same outer envelope (id, type, api_version, created_at, project_id, data). When new types ship, you subscribe to them in Hub and branch on type—you do not need a new integration pattern.

Available event types

The catalog starts with account-link lifecycle events. More Audience event types will be added over time; treat the table below as the current set, not the final set.

Event	Fired when
`audience_account_linked`	A player links an external account
`audience_account_unlinked`	A player disconnects an external account

Select the types you care about when you create or edit the webhook in Hub. Unsupported or future types simply do not appear until they are released.

Configure in Hub

Go to Hub → Settings → Webhooks → Add Webhook, enter your HTTPS URL, and choose which Audience event types to receive.

Payload shape

Every event uses this envelope. The data object is type-specific.

{
  "id": "evt_4cea103e-9148-476e-b634-5a31b4dc58de",
  "type": "audience_account_linked",
  "api_version": "2026-05-01",
  "created_at": "2026-05-01T10:30:00.000000000Z",
  "project_id": "353b1f6c-7dde-460c-9e5a-0711949e71f0",
  "data": {}
}

Account link and unlink

For audience_account_linked and audience_account_unlinked, data contains the player and linked account:

{
  "player": {
    "id": "auth0|abc123"
  },
  "linked_account": {
    "provider": "steam",
    "provider_account_id": "76561198728595133",
    "username": "playername",
    "linked_at": "2026-05-01T10:29:58Z"
  }
}

For unlink events, type is audience_account_unlinked. All other fields are identical. Supported provider values today: steam, discord, epic_games, x, telegram, tiktok, twitch

Verify the signature

Webhooks are signed by AWS SNS using RSA. Verify signatures using the sns-validator npm package. There is no shared secret or custom header. SNS delivers messages with Content-Type: text/plain. If you use Express, configure a raw text body parser for your webhook route:

app.use('/webhooks/immutable', express.text({ type: '*/*' }));
app.use('/webhooks/immutable', (req, res, next) => {
  if (typeof req.body === 'string') req.body = JSON.parse(req.body);
  next();
});

Then verify the signature and topic ARN:

import MessageValidator from 'sns-validator';

const validator = new MessageValidator();
const TOPIC_ARN = 'arn:aws:sns:us-east-2:362750628221:webhook-outbound-prod';

app.post('/webhooks/immutable', (req, res) => {
  res.status(200).send('OK');

  validator.validate(req.body, (err, message) => {
    if (err) {
      console.error('Invalid SNS signature', err);
      return;
    }

    if (message.TopicArn !== TOPIC_ARN) {
      console.error('Unexpected topic ARN', message.TopicArn);
      return;
    }

    if (message.Type === 'SubscriptionConfirmation') {
      fetch(message.SubscribeURL);
      return;
    }

    const event = JSON.parse(message.Message);
    handleEvent(event);
  });
});

Checking TopicArn confirms the event originated from Immutable’s infrastructure and not a third-party SNS topic. Handle events by switching on event.type so new types can be added without changing verification.

Retry policy

SNS retries failed deliveries automatically according to the SNS delivery retry policy. There is no manual retry in Hub. If your endpoint is unavailable for an extended period, events may be permanently dropped.

Best practices

Respond quickly. Return 200 to SNS immediately and process the event asynchronously to avoid delivery timeouts.
Deduplicate. Use the id field to detect duplicate deliveries. The same event may arrive more than once.
Scope by project. The project_id field identifies which of your projects the player belongs to. A player can appear in multiple projects and trigger events for each.
Ignore unknown types safely. Log and skip type values your code does not recognize so catalog growth does not break your endpoint.

PRODUCTS

GUIDES

How delivery works

Available event types

Configure in Hub

Payload shape

Account link and unlink

Verify the signature

Retry policy

Best practices

​How delivery works

​Available event types

​Configure in Hub

​Payload shape

​Account link and unlink

​Verify the signature

​Retry policy

​Best practices

How delivery works

Available event types

Configure in Hub

Payload shape

Account link and unlink

Verify the signature

Retry policy

Best practices