> ## Documentation Index
> Fetch the complete documentation index at: https://api-portal.etoro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> How etoro delivers account events to your Azure Event Hub. Each event payload is documented under Events.

## Purpose and scope

When an associated user's data changes on etoro, etoro can publish an event to your platform. Delivery is **push onto Azure Event Hub**: etoro writes the message, and your consumer reads it. This is the opposite direction from [Reporting events to etoro](https://api-portal.etoro.com/partners/integration.md#reporting-events-to-etoro), where your backend calls the Partners API.

Event delivery is provisioned per partner. If your integration agreement does not include outbound events, this page does not apply until etoro enables it for your application.

> [!NOTE]
>
> Connection details — Event Hub namespace, hub name, consumer group, and access material — are issued by your etoro contact when the integration is provisioned. They are not self-service and are not listed in this portal.

## Delivery

| Item | Contract |
| - | - |
| Transport | Azure Event Hub |
| Direction | etoro publishes; the partner consumes |
| Hub | One Event Hub per partner application, dedicated to that partner |
| Payload | JSON body on each Event Hub message |
| User identity | `eventMetadata.externalUserId` — the same opaque handle used elsewhere in the partner integration. Never a customer id from etoro |

etoro publishes an event only when the user has an associated account on your platform **and** the change is relevant to the field set approved for your application. If neither condition holds, no message is written to your hub.

## Message envelope

Every message body is a JSON object with two properties:

| Field | Type | Description |
| - | - | - |
| `eventData` | string | A **JSON-encoded string** of the event-specific payload. Parse the outer object first, then parse this string a second time. |
| `eventMetadata` | object | Delivery metadata shared by every event type |

### `eventMetadata`

| Field | Type | Description |
| - | - | - |
| `correlationId` | string (UUID) | Stable identifier for this event. Retain it for support and reconciliation. |
| `eventType` | string | Discriminator for the payload inside `eventData`. Each type is documented under Events. The current one is [KYC](https://api-portal.etoro.com/partners/events/kyc-updates.md). |
| `createdAt` | string (date-time) | When etoro created the event, UTC, ISO 8601 |
| `eventDataVersion` | string | Version of the `eventData` contract for this `eventType`. Treat unknown versions as unsupported until your etoro contact confirms them. |
| `externalUserId` | string | The associated user on your side |

### Example

```json theme={null}
{
  "eventData": "<JSON_STRING>",
  "eventMetadata": {
    "correlationId": "8f1c2a40-6b2e-4d1a-9c3e-1a2b3c4d5e6f",
    "eventType": "<EVENT_TYPE>",
    "createdAt": "2026-10-21T08:03:00.0000000Z",
    "eventDataVersion": "<VERSION>",
    "externalUserId": "<EXTERNAL_USER_ID>"
  }
}
```

Keys are camelCase. Consumers should keep advancing the partition when they see an unknown `eventType` or `eventDataVersion`, and confirm support with their etoro contact before handling new ones. Additional optional fields may appear in later versions. The payload inside `eventData` depends on `eventType` and is documented on that event's page under Events.

## Operational rules

**1. Parse the envelope, then parse eventData**

`eventData` is a string. A single `JSON.parse` (or equivalent) leaves you with a string, not an object. Deserialize it again before reading the payload for that `eventType`.

**2. Branch on eventType**

Route handling by `eventMetadata.eventType`. Ignore event types your integration does not implement, and keep the consumer advancing so an unknown type does not block the partition.

**3. Key users by externalUserId**

Match the event to your user record with `eventMetadata.externalUserId`. Do not expect an etoro customer id in the payload.

**4. Treat the message as a change signal**

An event names what changed. It is not a full snapshot of the user, and it does not include the new values. Read those through the Partners API only where your integration is approved to.

**5. Retain correlationId**

Store `correlationId` with your processing record. It is the reference etoro uses when tracing whether a given change was delivered.

## Related

> **[Reporting events to etoro](https://api-portal.etoro.com/partners/integration.md#reporting-events-to-etoro)**
>
> The partner-to-etoro direction: deposit notifications and related reporting over the Partners API.

> **[Partner integration flow](https://api-portal.etoro.com/partners/integration.md)**
>
> Non-interactive tokens, account association, and data-sharing rules.

> **[Data sharing and PII](https://api-portal.etoro.com/partners/integration.md#data-sharing-and-pii)**
>
> What personal data a partner may receive, and under which approval.

> **[KYC](https://api-portal.etoro.com/partners/events/kyc-updates.md)**
>
> Payload and field names for the KycUpdates event.

> **[Partners API reference](https://api-portal.etoro.com/partners-api-reference)**
>
> REST operations for reading approved KYC and account data after an event.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.