Skip to content

Social SDK webhook events doc update #7822

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
merged 3 commits into from
Sep 9, 2025
Merged

Social SDK webhook events doc update #7822

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
816c1f5
adding new webhook events
meka-ddev Sep 3, 2025
2001e74
additional edits to webhook events
meka-ddev Sep 3, 2025
72d59b9
restructured and fixed some anchor links
meka-ddev Sep 3, 2025
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
277 changes: 271 additions & 6 deletions docs/events/webhook-events.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,12 +132,18 @@ The table below includes the different webhook event types your app can subscrib

The "Value" column corresponds to the event's `type` field value in the [event body object](/docs/events/webhook-events#event-body-object).

| Name | Value | Description |
|----------------------------------------------------------------------------------|----------------------------|------------------------------------------------------------------------|
| [Application Authorized](/docs/events/webhook-events#application-authorized) | `APPLICATION_AUTHORIZED` | Sent when an app was authorized by a user to a server or their account |
| [Application Deauthorized](/docs/events/webhook-events#application-deauthorized) | `APPLICATION_DEAUTHORIZED` | Sent when an app was deauthorized by a user |
| [Entitlement Create](/docs/events/webhook-events#entitlement-create) | `ENTITLEMENT_CREATE` | Entitlement was created |
| [Quest User Enrollment](/docs/events/webhook-events#quest-user-enrollment) | `QUEST_USER_ENROLLMENT` | User was added to a Quest (currently unavailable) |
| Name | Value | Description |
|--------------------------------------------------------------------------------------|------------------------------|---------------------------------------------------------------------------|
| [Application Authorized](/docs/events/webhook-events#application-authorized) | `APPLICATION_AUTHORIZED` | Sent when an app was authorized by a user to a server or their account |
| [Application Deauthorized](/docs/events/webhook-events#application-deauthorized) | `APPLICATION_DEAUTHORIZED` | Sent when an app was deauthorized by a user |
| [Entitlement Create](/docs/events/webhook-events#entitlement-create) | `ENTITLEMENT_CREATE` | Entitlement was created |
| [Quest User Enrollment](/docs/events/webhook-events#quest-user-enrollment) | `QUEST_USER_ENROLLMENT` | User was added to a Quest (currently unavailable) |
| [Lobby Message Create](/docs/events/webhook-events#lobby-message-create) | `LOBBY_MESSAGE_CREATE` | Sent when a message is created in a lobby |
| [Lobby Message Update](/docs/events/webhook-events#lobby-message-update) | `LOBBY_MESSAGE_UPDATE` | Sent when a message is updated in a lobby |
| [Lobby Message Delete](/docs/events/webhook-events#lobby-message-delete) | `LOBBY_MESSAGE_DELETE` | Sent when a message is deleted from a lobby |
| [Game Direct Message Create](/docs/events/webhook-events#game-direct-message-create) | `GAME_DIRECT_MESSAGE_CREATE` | Sent when a direct message is created during an active Social SDK session |
| [Game Direct Message Update](/docs/events/webhook-events#game-direct-message-update) | `GAME_DIRECT_MESSAGE_UPDATE` | Sent when a direct message is updated during an active Social SDK session |
| [Game Direct Message Delete](/docs/events/webhook-events#game-direct-message-delete) | `GAME_DIRECT_MESSAGE_DELETE` | Sent when a direct message is deleted during an active Social SDK session |

#### Application Authorized

Expand Down Expand Up @@ -245,3 +251,262 @@ This event cannot be received by apps at this time. It's documented because it a
:::

`QUEST_USER_ENROLLMENT` is sent when a user is added to a Quest on Discord.

#### Lobby Message Create

`LOBBY_MESSAGE_CREATE` is sent when a message is created in a lobby.

###### Lobby Message Create Structure

The inner payload is a [lobby message object](/docs/events/webhook-events#lobby-message-object).

###### Lobby Message Create Example

```json
{
"version": 1,
"application_id": "1234567765431056709",
"type": 1,
"event": {
"type": "LOBBY_MESSAGE_CREATE",
"timestamp": "2024-10-18T18:41:21.109604",
"data": {
"id": "1397729799727878254",
"type": 0,
"content": "welcome to the party!",
"lobby_id": "1397729744753266719",
"channel_id": "1397729744753266719",
"author": {
// user data
},
"flags": 65536,
"application_id": "1234567765431056709"
}
}
}
```

#### Lobby Message Update

`LOBBY_MESSAGE_UPDATE` is sent when a message is updated in a lobby.

###### Lobby Message Update Structure

The inner payload is a [lobby message object](/docs/events/webhook-events#lobby-message-object) with additional fields for message updates.

###### Lobby Message Update Example

```json
{
"version": 1,
"application_id": "1234567765431056709",
"type": 1,
"event": {
"type": "LOBBY_MESSAGE_UPDATE",
"timestamp": "2025-08-05T20:39:19.587872",
"data": {
"id": "1402390388030832792",
"type": 0,
"content": "noice",
"lobby_id": "1402385687281537066",
"channel_id": "1402389638311841883",
"author": {
// user data
},
"edited_timestamp": "2025-08-05T20:39:19.557970+00:00",
"flags": 0,
"timestamp": "2025-08-05T20:38:43.660000+00:00"
}
}
}
```

#### Lobby Message Delete

`LOBBY_MESSAGE_DELETE` is sent when a message is deleted from a lobby.

###### Lobby Message Delete Structure

| Field | Type | Description |
|----------|-----------|-----------------------------------------------|
| id | snowflake | ID of the deleted message |
| lobby_id | snowflake | ID of the lobby where the message was deleted |

###### Lobby Message Delete Example

```json
{
"version": 1,
"application_id": "1234567765431056709",
"type": 1,
"event": {
"type": "LOBBY_MESSAGE_DELETE",
"timestamp": "2025-08-05T21:44:09.412957",
"data": {
"id": "1402406637632884857",
"lobby_id": "1402399883394285659"
}
}
}
```

#### Game Direct Message Create

`GAME_DIRECT_MESSAGE_CREATE` is sent when a direct message is created while at least one user has an active Social SDK session.

###### Game Direct Message Create Structure

The inner payload is a [message object](/docs/events/webhook-events#message-object) or [passthrough message object](/docs/events/webhook-events#passthrough-message-object).

###### Game Direct Message Create Example

```json
{
"version": 1,
"application_id": "1234567765431056709",
"type": 1,
"event": {
"type": "GAME_DIRECT_MESSAGE_CREATE",
"timestamp": "2025-08-14T18:09:38.063234",
"data": {
"id": "1405614357781545021",
"type": 0,
"content": "get in friend, we're going raiding",
"channel_id": "1405604229820715098",
"author": {
// user data
},
"timestamp": "2025-08-14T18:09:37.947000+00:00",
"application_id": "1234567765431056709",
"attachments": []
}
}
}
```

#### Game Direct Message Update

`GAME_DIRECT_MESSAGE_UPDATE` is sent when a direct message is updated while at least one user has an active Social SDK session.

###### Game Direct Message Update Structure

The inner payload is a [message object](/docs/events/webhook-events#message-object) or [passthrough message object](/docs/events/webhook-events#passthrough-message-object).

###### Game Direct Message Update Example

```json
{
"version": 1,
"application_id": "1234567765431056709",
"type": 1,
"event": {
"type": "GAME_DIRECT_MESSAGE_UPDATE",
"timestamp": "2025-08-14T16:44:31.847073",
"data": {
"id": "1405591838810706081",
"content": "almost ready to queue?",
"channel_id": "1404960877324533784",
"author": {
// user data
},
"recipient_id": "1404960877324533784"
}
}
}
```

#### Game Direct Message Delete

`GAME_DIRECT_MESSAGE_DELETE` is sent when a direct message is deleted while at least one user has an active Social SDK session.

###### Game Direct Message Delete Structure

The inner payload is a [message object](/docs/events/webhook-events#message-object) or [passthrough message object](/docs/events/webhook-events#passthrough-message-object).

###### Game Direct Message Delete Example

```json
{
"version": 1,
"application_id": "1234567765431056709",
"type": 1,
"event": {
"type": "GAME_DIRECT_MESSAGE_DELETE",
"timestamp": "2025-08-20T17:01:50.099204",
"data": {
"id": "1407771600643686503",
"type": 0,
"content": "cant make it in time",
"channel_id": "1405604229820715098",
"author": {
// user data
},
"timestamp": "2025-08-20T17:01:44.725000+00:00",
"flags": 0,
"attachments": [],
"components": []
}
}
}
```

## Social SDK Message Objects

Discord Social SDK utilizes specialized message objects for lobby and direct message events that occur during active game sessions. These objects extend or modify the standard Discord message structure to support communication features.

- [Lobby messages](/docs/events/webhook-events#lobby-message-object) include lobby-specific fields like `lobby_id`
- [Standard Discord messages](/docs/events/webhook-events#message-object) in SDK contexts may include additional fields
- [Passthrough messages](/docs/events/webhook-events#passthrough-message-object) are used for communication between provisional accounts

These objects are used in the webhook events `LOBBY_MESSAGE_*` and `GAME_DIRECT_MESSAGE_*` depending on the messaging context.

### Lobby Message Object

Represents a message sent in a lobby or [Linked Channel](/docs/discord-social-sdk/development-guides/linked-channels).

###### Lobby Message Structure

| Field | Type | Description |
|-----------------|----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| id | snowflake | ID of the message |
| type | integer | [Type of message](/docs/resources/message#message-object-message-types) |
| content | string | Contents of the message |
| lobby_id | snowflake | ID of the lobby where the message was sent |
| channel_id | snowflake | ID of the channel the message was sent in |
| author | [user object](/docs/resources/user#user-object-user-structure) | Author of the message |
| metadata? | object | Additional metadata for the message (key-value pairs) |
| flags | integer | [Message flags](/docs/resources/message#message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) |
| application_id? | snowflake | ID of the application (only present during active Social SDK sessions) |

### Message Object

Standard [Message Object](/docs/resources/message#messages-resource) with additional fields.

###### Additional Fields

| Field | Type | Description |
|-----------|----------------------------------------------------------|-----------------------------------------------------------------------------------------|
| lobby_id? | snowflake | ID of the lobby where the message was created (only present in Linked Channel messages) |
| channel | [channel object](/docs/resources/channel#channel-object) | Channel object with recipient information |

### Passthrough Message Object

Represents a message between provisional users that exists only in-game.

###### Passthrough Message Structure

| Field | Type | Description |
|----------------|----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| id | snowflake | ID of the message |
| type | integer | [Type of message](/docs/resources/message#message-object-message-types) |
| content | string | Contents of the message |
| channel_id | snowflake | ID of the channel the message was sent in |
| recipient_id | snowflake | ID of the message recipient |
| author | [user object](/docs/resources/user#user-object-user-structure) | Author of the message |
| flags | integer | [Message flags](/docs/resources/message#message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) |
| application_id | snowflake | ID of the application that created the message |
| channel | [channel object](/docs/resources/channel#channel-object) | Channel object with recipient information |

:::info
When both users in a direct message are provisional accounts, messages become "passthrough messages" that are only visible in-game and use this specialized structure.
:::