Hype Train - EventSub Reference

Hype Train Begin

The channel.hype_train.begin subscription type sends a notification when a Hype Train begins on the specified channel. In addition to a channel.hype_train.begin event, one channel.hype_train.progress event will be sent for each contribution that caused the Hype Train to begin. EventSub does not make strong assurances about the order of message delivery, so it is possible to receive channel.hype_train.progress notifications before you receive the corresponding channel.hype_train.begin notification. After the Hype Train begins, any additional cheers or subscriptions on the channel will cause channel.hype_train.progress notifications to be sent. When the Hype Train is over, channel.hype_train.end is emitted.

Subscription

Type: channel.hype_train.begin
Version: 2

Authorization

Requires one of the following:

A user access token that includes the channel:read:hype_train scope.
An app access token.The application, through prior authorization, must have been granted:
- The channel:read:hype_train scope for the user represented by the broadcaster_user_id event condition.

Subscription Request Body

typeStringRequired
The subscription type name: channel.hype_train.begin.
versionStringRequired
The subscription type version: 2.
conditionObjectRequired
Subscription-specific parameters. Pass in the broadcaster user ID for the channel you want to Hype Train begin notifications for.
Hide child attributesShow child attributes
- condition.broadcaster_user_idStringRequired
  The ID of the broadcaster that you want to get Hype Train begin notifications for.
transportObjectRequired
Transport-specific parameters.
Hide child attributesShow child attributes
- transport.methodStringRequired
  The transport method for EventSub.
  Possible values
  - webhook
  - websocket
  - conduit
- transport.callbackString
  The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
  
  Specify this field only if method is set to webhook.
  
  NOTE: Redirects are not followed.
- transport.secretString
  The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
  
  Specify this field only if the method is set to webhook.
- transport.session_idString
  An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
  
  Specify this field only if the method is set to websocket.
- transport.conduit_idString
  An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
  
  Specify this field only if the method is set to conduit.

Event Payload

subscriptionObject
Metadata about the subscription.
Hide child attributesShow child attributes
- subscription.idString
  The Subscription ID of the subscription.
- subscription.typeString
  The notification's subscription type.
- subscription.versionString
  The version of the subscription.
- subscription.statusString
  The status of the subscription.
- subscription.costInteger
  How much the subscription counts against your limit. See Subscription Limits for more information.
- subscription.conditionObject
  Subscription-specific parameters.
  Hide child attributesShow child attributes
  - subscription.condition.broadcaster_user_idString
    The ID of the broadcaster that you want to get Hype Train begin notifications for.
- subscription.created_atString
  The time the notification was created.
- subscription.transportObject
  Transport-specific parameters.
  Hide child attributesShow child attributes
  - subscription.transport.methodString
    The transport method for EventSub.
    Possible values
    webhook
    websocket
    conduit
  - subscription.transport.callbackString
    The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
    
    Specify this field only if method is set to webhook.
    
    NOTE: Redirects are not followed.
  - subscription.transport.secretString
    The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
    
    Specify this field only if the method is set to webhook.
  - subscription.transport.session_idString
    An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
    
    Specify this field only if the method is set to websocket.
  - subscription.transport.conduit_idString
    An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
    
    Specify this field only if the method is set to conduit.
eventObject
The event information.
Hide child attributesShow child attributes
- event.idString
  The Hype Train ID.
- event.broadcaster_user_idString
  The requested broadcaster ID.
- event.broadcaster_user_loginString
  The requested broadcaster login.
- event.broadcaster_user_nameString
  The requested broadcaster display name.
- event.totalInteger
  Total points contributed to the Hype Train.
- event.progressInteger
  The number of points contributed to the Hype Train at the current level.
- event.goalInteger
  The number of points required to reach the next level.
- event.top_contributionsObject[]
  The contributors with the most points contributed.
  Hide child attributesShow child attributes
  - event.top_contributions.user_idString
    The ID of the user that made the contribution.
  - event.top_contributions.user_loginString
    The user's login name.
  - event.top_contributions.user_nameString
    The user's display name.
  - event.top_contributions.typeString
    The contribution method used.
    Possible values
    bits
    Bits contributions with Cheering and Power-ups.
    subscription
    Subscription activity like subscribing or gifting subscriptions.
    other
    Covers other contribution methods not listed.
  - event.top_contributions.totalInteger
    The total amount contributed. If type is bits, total represents the amount of Bits used. If type is subscription, total is 500, 1000, or 2500 to represent tier 1, 2, or 3 subscriptions, respectively.
- event.levelInteger
  The current level of the Hype Train.
- event.all_time_high_levelInteger
  The all-time high level this type of Hype Train has reached for this broadcaster.
- event.all_time_high_totalInteger
  The all-time high total this type of Hype Train has reached for this broadcaster.
- event.shared_train_participantsObject[]Nullable
  Non-null for a shared Hype Train. Contains the list of broadcasters in the shared Hype Train.
  Hide child attributesShow child attributes
  - event.shared_train_participants.broadcaster_user_idString
    The ID of the broadcaster participating in the shared Hype Train.
  - event.shared_train_participants.broadcaster_user_loginString
    The login of the broadcaster participating in the shared Hype Train.
  - event.shared_train_participants.broadcaster_user_nameString
    The display name of the broadcaster participating in the shared Hype Train.
- event.started_atString
  The time when the Hype Train started.
- event.expires_atString
  The time when the Hype Train expires. The expiration is extended when the Hype Train reaches a new level.
- event.typeString
  The type of the Hype Train.
  Possible values
  - treasure
  - golden_kappa
  - regular
- event.is_shared_trainBoolean
  Indicates if the Hype Train is shared. When true, shared_train_participants will contain the list of broadcasters the train is shared with.

Subscription Request Body Example

{
  "type": "channel.hype_train.begin",
  "version": "2",
  "condition": {
    "broadcaster_user_id": "1337"
  },
  "transport": {
    "method": "webhook",
    "callback": "https://example.com/webhooks/callback",
    "secret": "s3cRe7"
  }
}

{
  "type": "channel.hype_train.begin",
  "version": "2",
  "condition": {
    "broadcaster_user_id": "1337"
  },
  "transport": {
    "method": "websocket",
    "session_id": "AQoQexAWVYKSTIu4ec_2VAxyuhAB"
  }
}

{
  "type": "channel.hype_train.begin",
  "version": "2",
  "condition": {
    "broadcaster_user_id": "1337"
  },
  "transport": {
    "method": "conduit",
    "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac"
  }
}

Event Payload Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.hype_train.begin",
        "version": "2",
        "status": "enabled",
        "cost": 0,
        "condition": {
            "broadcaster_user_id": "1337"
        },
        "transport": {
            "method": "webhook",
            "callback": "https://example.com/webhooks/callback"
        },
        "created_at": "2019-11-16T10:11:12.634234626Z"
    },
    "event": {
        "id": "1b0AsbInCHZW2SQFQkCzqN07Ib2",
        "broadcaster_user_id": "1337",
        "broadcaster_user_login": "cool_user",
        "broadcaster_user_name": "Cool_User",
        "total": 137,
        "progress": 137,
        "goal": 500,
        "top_contributions": [
            {
                "user_id": "123",
                "user_login": "pogchamp",
                "user_name": "PogChamp",
                "type": "bits",
                "total": 50
            }
        ],
        "shared_train_participants": null,
        "level": 1,
        "started_at": "2020-07-15T17:16:03.17106713Z",
        "expires_at": "2020-07-15T17:16:11.17106713Z",
        "is_shared_train": false,
        "type": "regular",
        "all_time_high_level": 4,
        "all_time_high_total": 2845
    }
}

Hype Train End

The channel.hype_train.end subscription type sends a notification when a Hype Train ends on the specified channel.

Subscription

Type: channel.hype_train.end
Version: 2

Authorization

Requires one of the following:

A user access token that includes the channel:read:hype_train scope.
An app access token.The application, through prior authorization, must have been granted:
- The channel:read:hype_train scope for the user represented by the broadcaster_user_id event condition.

Subscription Request Body

typeStringRequired
The subscription type name: channel.hype_train.end.
versionStringRequired
The subscription type version: 2.
conditionObjectRequired
Subscription-specific parameters. Pass in the broadcaster user ID for the channel you want to Hype Train end notifications for.
Hide child attributesShow child attributes
- condition.broadcaster_user_idStringRequired
  The ID of the broadcaster that you want to get Hype Train end notifications for.
transportObjectRequired
Transport-specific parameters.
Hide child attributesShow child attributes
- transport.methodStringRequired
  The transport method for EventSub.
  Possible values
  - webhook
  - websocket
  - conduit
- transport.callbackString
  The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
  
  Specify this field only if method is set to webhook.
  
  NOTE: Redirects are not followed.
- transport.secretString
  The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
  
  Specify this field only if the method is set to webhook.
- transport.session_idString
  An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
  
  Specify this field only if the method is set to websocket.
- transport.conduit_idString
  An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
  
  Specify this field only if the method is set to conduit.

Event Payload

subscriptionObject
Metadata about the subscription.
Hide child attributesShow child attributes
- subscription.idString
  The Subscription ID of the subscription.
- subscription.typeString
  The notification's subscription type.
- subscription.versionString
  The version of the subscription.
- subscription.statusString
  The status of the subscription.
- subscription.costInteger
  How much the subscription counts against your limit. See Subscription Limits for more information.
- subscription.conditionObject
  Subscription-specific parameters.
  Hide child attributesShow child attributes
  - subscription.condition.broadcaster_user_idString
    The ID of the broadcaster that you want to get Hype Train end notifications for.
- subscription.created_atString
  The time the notification was created.
- subscription.transportObject
  Transport-specific parameters.
  Hide child attributesShow child attributes
  - subscription.transport.methodString
    The transport method for EventSub.
    Possible values
    webhook
    websocket
    conduit
  - subscription.transport.callbackString
    The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
    
    Specify this field only if method is set to webhook.
    
    NOTE: Redirects are not followed.
  - subscription.transport.secretString
    The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
    
    Specify this field only if the method is set to webhook.
  - subscription.transport.session_idString
    An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
    
    Specify this field only if the method is set to websocket.
  - subscription.transport.conduit_idString
    An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
    
    Specify this field only if the method is set to conduit.
eventObject
The event information.
Hide child attributesShow child attributes
- event.idString
  The Hype Train ID.
- event.broadcaster_user_idString
  The requested broadcaster ID.
- event.broadcaster_user_loginString
  The requested broadcaster login.
- event.broadcaster_user_nameString
  The requested broadcaster display name.
- event.totalInteger
  Total points contributed to the Hype Train.
- event.top_contributionsObject[]
  The contributors with the most points contributed.
  Hide child attributesShow child attributes
  - event.top_contributions.user_idString
    The ID of the user that made the contribution.
  - event.top_contributions.user_loginString
    The user's login name.
  - event.top_contributions.user_nameString
    The user's display name.
  - event.top_contributions.typeString
    The contribution method used.
    Possible values
    bits
    Bits contributions with Cheering, Power-ups, and Extensions.
    subscription
    Subscription activity like subscribing or gifting subscriptions.
    other
    Covers other contribution methods not listed.
  - event.top_contributions.totalInteger
    The total amount contributed. If type is bits, total represents the amount of Bits used. If type is subscription, total is 500, 1000, or 2500 to represent tier 1, 2, or 3 subscriptions, respectively.
- event.levelInteger
  The current level of the Hype Train.
- event.shared_train_participantsObject[]Nullable
  Non-null for a shared Hype Train. Contains the list of broadcasters in the shared Hype Train.
  Hide child attributesShow child attributes
  - event.shared_train_participants.broadcaster_user_idString
    The ID of the broadcaster participating in the shared Hype Train.
  - event.shared_train_participants.broadcaster_user_loginString
    The login of the broadcaster participating in the shared Hype Train.
  - event.shared_train_participants.broadcaster_user_nameString
    The display name of the broadcaster participating in the shared Hype Train.
- event.started_atString
  The time when the Hype Train started.
- event.cooldown_ends_atString
  The time when the Hype Train cooldown ends so that the next Hype Train can start.
- event.ended_atString
  The time when the Hype Train ended.
- event.typeString
  The type of the Hype Train.
  Possible values
  - treasure
  - golden_kappa
  - regular
- event.is_shared_trainBoolean
  Indicates if the Hype Train is shared. When true, shared_train_participants will contain the list of broadcasters the train is shared with.

Subscription Request Body Example

{
  "type": "channel.hype_train.end",
  "version": "2",
  "condition": {
    "broadcaster_user_id": "1337"
  },
  "transport": {
    "method": "webhook",
    "callback": "https://example.com/webhooks/callback",
    "secret": "s3cRe7"
  }
}

{
  "type": "channel.hype_train.end",
  "version": "2",
  "condition": {
    "broadcaster_user_id": "1337"
  },
  "transport": {
    "method": "websocket",
    "session_id": "AQoQexAWVYKSTIu4ec_2VAxyuhAB"
  }
}

{
  "type": "channel.hype_train.end",
  "version": "2",
  "condition": {
    "broadcaster_user_id": "1337"
  },
  "transport": {
    "method": "conduit",
    "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac"
  }
}

Event Payload Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.hype_train.end",
        "version": "2",
        "status": "enabled",
        "cost": 0,
        "condition": {
            "broadcaster_user_id": "1337"
        },
        "transport": {
            "method": "webhook",
            "callback": "https://example.com/webhooks/callback"
        },
        "created_at": "2019-11-16T10:11:12.634234626Z"
    },
    "event": {
        "id": "1b0AsbInCHZW2SQFQkCzqN07Ib2",
        "broadcaster_user_id": "1337",
        "broadcaster_user_login": "cool_user",
        "broadcaster_user_name": "Cool_User",
        "total": 137,
        "top_contributions": [
            {
                "user_id": "123",
                "user_login": "pogchamp",
                "user_name": "PogChamp",
                "type": "bits",
                "total": 50
            }
        ],
        "shared_train_participants": null,
        "level": 1,
        "started_at": "2020-07-15T17:16:03.17106713Z",
        "ended_at": "2020-07-15T17:16:11.17106713Z",
        "cooldown_ends_at": "2020-07-16T17:16:11.17106713Z",
        "is_shared_train": false,
        "type": "regular"
    }
}

Hype Train Progress

The channel.hype_train.progress subscription type sends a notification when a Hype Train makes progress on the specified channel. channel.hype_train.progress notifications are sent periodically while a Hype Train is making progress. EventSub does not make strong assurances about the order of message delivery, so it is possible to receive channel.hype_train.progress before you receive the corresponding channel.hype_train.begin. When the Hype Train is over, channel.hype_train.end is emitted.

Subscription

Type: channel.hype_train.progress
Version: 2

Authorization

Requires one of the following:

A user access token that includes the channel:read:hype_train scope.
An app access token.The application, through prior authorization, must have been granted:
- The channel:read:hype_train scope for the user represented by the broadcaster_user_id event condition.

Subscription Request Body

typeStringRequired
The subscription type name: channel.hype_train.progress.
versionStringRequired
The subscription type version: 2.
conditionObjectRequired
Subscription-specific parameters. Pass in the broadcaster user ID for the channel you want to Hype Train progress notifications for.
Hide child attributesShow child attributes
- condition.broadcaster_user_idStringRequired
  The ID of the broadcaster that you want to get Hype Train progress notifications for.
transportObjectRequired
Transport-specific parameters.
Hide child attributesShow child attributes
- transport.methodStringRequired
  The transport method for EventSub.
  Possible values
  - webhook
  - websocket
  - conduit
- transport.callbackString
  The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
  
  Specify this field only if method is set to webhook.
  
  NOTE: Redirects are not followed.
- transport.secretString
  The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
  
  Specify this field only if the method is set to webhook.
- transport.session_idString
  An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
  
  Specify this field only if the method is set to websocket.
- transport.conduit_idString
  An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
  
  Specify this field only if the method is set to conduit.

Event Payload

subscriptionObject
Metadata about the subscription.
Hide child attributesShow child attributes
- subscription.idString
  The Subscription ID of the subscription.
- subscription.typeString
  The notification's subscription type.
- subscription.versionString
  The version of the subscription.
- subscription.statusString
  The status of the subscription.
- subscription.costInteger
  How much the subscription counts against your limit. See Subscription Limits for more information.
- subscription.conditionObject
  Subscription-specific parameters.
  Hide child attributesShow child attributes
  - subscription.condition.broadcaster_user_idString
    The ID of the broadcaster that you want to get Hype Train progress notifications for.
- subscription.created_atString
  The time the notification was created.
- subscription.transportObject
  Transport-specific parameters.
  Hide child attributesShow child attributes
  - subscription.transport.methodString
    The transport method for EventSub.
    Possible values
    webhook
    websocket
    conduit
  - subscription.transport.callbackString
    The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
    
    Specify this field only if method is set to webhook.
    
    NOTE: Redirects are not followed.
  - subscription.transport.secretString
    The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
    
    Specify this field only if the method is set to webhook.
  - subscription.transport.session_idString
    An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
    
    Specify this field only if the method is set to websocket.
  - subscription.transport.conduit_idString
    An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
    
    Specify this field only if the method is set to conduit.
eventObject
The event information.
Hide child attributesShow child attributes
- event.idString
  The Hype Train ID.
- event.broadcaster_user_idString
  The requested broadcaster ID.
- event.broadcaster_user_loginString
  The requested broadcaster login.
- event.broadcaster_user_nameString
  The requested broadcaster display name.
- event.totalInteger
  Total points contributed to the Hype Train.
- event.progressInteger
  The number of points contributed to the Hype Train at the current level.
- event.goalInteger
  The number of points required to reach the next level.
- event.top_contributionsObject[]
  The contributors with the most points contributed.
  Hide child attributesShow child attributes
  - event.top_contributions.user_idString
    The ID of the user that made the contribution.
  - event.top_contributions.user_loginString
    The user's login name.
  - event.top_contributions.user_nameString
    The user's display name.
  - event.top_contributions.typeString
    The contribution method used.
    Possible values
    bits
    Bits contributions with Cheering, Power-ups, and Extensions.
    subscription
    Subscription activity like subscribing or gifting subscriptions.
    other
    Covers other contribution methods not listed.
  - event.top_contributions.totalInteger
    The total amount contributed. If type is bits, total represents the amount of Bits used. If type is subscription, total is 500, 1000, or 2500 to represent tier 1, 2, or 3 subscriptions, respectively.
- event.levelInteger
  The current level of the Hype Train.
- event.shared_train_participantsObject[]Nullable
  Non-null for a shared Hype Train. Contains the list of broadcasters in the shared Hype Train.
  Hide child attributesShow child attributes
  - event.shared_train_participants.broadcaster_user_idString
    The ID of the broadcaster participating in the shared Hype Train.
  - event.shared_train_participants.broadcaster_user_loginString
    The login of the broadcaster participating in the shared Hype Train.
  - event.shared_train_participants.broadcaster_user_nameString
    The display name of the broadcaster participating in the shared Hype Train.
- event.started_atString
  The time when the Hype Train started.
- event.expires_atString
  The time when the Hype Train expires. The expiration is extended when the Hype Train reaches a new level.
- event.typeString
  The type of the Hype Train.
  Possible values
  - treasure
  - golden_kappa
  - regular
- event.is_shared_trainBoolean
  Indicates if the Hype Train is shared. When true, shared_train_participants will contain the list of broadcasters the train is shared with.

Subscription Request Body Example

{
  "type": "channel.hype_train.progress",
  "version": "2",
  "condition": {
    "broadcaster_user_id": "1337"
  },
  "transport": {
    "method": "webhook",
    "callback": "https://example.com/webhooks/callback",
    "secret": "s3cRe7"
  }
}

{
  "type": "channel.hype_train.progress",
  "version": "2",
  "condition": {
    "broadcaster_user_id": "1337"
  },
  "transport": {
    "method": "websocket",
    "session_id": "AQoQexAWVYKSTIu4ec_2VAxyuhAB"
  }
}

{
  "type": "channel.hype_train.progress",
  "version": "2",
  "condition": {
    "broadcaster_user_id": "1337"
  },
  "transport": {
    "method": "conduit",
    "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac"
  }
}

Event Payload Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.hype_train.progress",
        "version": "2",
        "status": "enabled",
        "cost": 0,
        "condition": {
            "broadcaster_user_id": "1337"
        },
        "transport": {
            "method": "webhook",
            "callback": "https://example.com/webhooks/callback"
        },
        "created_at": "2019-11-16T10:11:12.634234626Z"
    },
    "event": {
        "id": "1b0AsbInCHZW2SQFQkCzqN07Ib2",
        "broadcaster_user_id": "1337",
        "broadcaster_user_login": "cool_user",
        "broadcaster_user_name": "Cool_User",
        "total": 137,
        "progress": 137,
        "goal": 500,
        "top_contributions": [
            {
                "user_id": "123",
                "user_login": "pogchamp",
                "user_name": "PogChamp",
                "type": "bits",
                "total": 50
            }
        ],
        "shared_train_participants": null,
        "level": 1,
        "started_at": "2020-07-15T17:16:03.17106713Z",
        "expires_at": "2020-07-15T17:16:11.17106713Z",
        "is_shared_train": false,
        "type": "regular"
    }
}