Contents
Twitch Channel Points Hackathon

EventSub Reference

Request fields

Name Type Required? Description
type string yes The subscription type name.
version string yes The subscription type version: 1.
condition  condition  yes Subscription-specific parameters. The parameters inside this object differ by subscription type and may differ by version.
transport  transport  yes Transport-specific parameters.

Response fields

Name Type Description
subscription  subscription  Contains subscription metadata.
event  event  The event information. The fields inside this object differ by subscription type.

Objects

Conditions

Channel Ban Condition

Name Type Required? Description
broadcaster_user_id string yes The broadcaster user ID for the channel you want to get ban notifications for.

Channel Subscribe Condition

Name Type Required? Description
broadcaster_user_id string yes The broadcaster user ID for the channel you want to get subscribe notifications for.

Channel Cheer Condition

Name Type Required? Description
broadcaster_user_id string yes The broadcaster user ID for the channel you want to get cheer notifications for.

Channel Update Condition

Name Type Required? Description
broadcaster_user_id string yes The broadcaster user ID for the channel you want to get updates for.

Channel Follow Condition

Name Type Required? Description
broadcaster_user_id string yes The broadcaster user ID for the channel you want to get follow notifications for.

Channel Unban Condition

Name Type Required? Description
broadcaster_user_id string yes The broadcaster user ID for the channel you want to get unban notifications for.

Channel Raid Condition

Name Type Required? Description
from_broadcaster_user_id string no The broadcaster user ID that created the channel raid you want to get notifications for. Use this parameter if you want to know when a specific broadcaster raids another broadcaster. The channel raid condition must include either from_broadcaster_user_id or to_broadcaster_user_id.
to_broadcaster_user_id string no The broadcaster user ID that received the channel raid you want to get notifications for. Use this parameter if you want to know when a specific broadcaster is raided by another broadcaster. The channel raid condition must include either from_broadcaster_user_id or to_broadcaster_user_id.

Channel Points Custom Reward Add Condition

Name Type Required? Description
broadcaster_user_id string yes The broadcaster user ID for the channel you want to receive channel points custom reward add notifications for.

Channel Points Custom Reward Update Condition

Name Type Required? Description
broadcaster_user_id string yes The broadcaster user ID for the channel you want to receive channel points custom reward update notifications for.
reward_id string no Optional. Specify a reward id to only receive notifications for a specific reward.

Channel Points Custom Reward Remove Condition

Name Type Required? Description
broadcaster_user_id string yes The broadcaster user ID for the channel you want to receive channel points custom reward remove notifications for.
reward_id string no Optional. Specify a reward id to only receive notifications for a specific reward.

Channel Points Custom Reward Redemption Add Condition

Name Type Required? Description
broadcaster_user_id string yes The broadcaster user ID for the channel you want to receive channel points custom reward redemption add notifications for.
reward_id string no Optional. Specify a reward id to only receive notifications for a specific reward.

Channel Points Custom Reward Redemption Update Condition

Name Type Required? Description
broadcaster_user_id string yes The broadcaster user ID for the channel you want to receive channel points custom reward redemption update notifications for.
reward_id string no Optional. Specify a reward id to only receive notifications for a specific reward.

Hype Train Begin Condition

Name Type Required? Description
broadcaster_user_id string yes The broadcaster user ID for the channel you want to hype train begin notifications for.

Hype Train Progress Condition

Name Type Required? Description
broadcaster_user_id string yes The broadcaster user ID for the channel you want to hype train progress notifications for.

Hype Train End Condition

Name Type Required? Description
broadcaster_user_id string yes The broadcaster user ID for the channel you want to hype train end notifications for.

Stream Online Condition

Name Type Required? Description
broadcaster_user_id string yes The broadcaster user ID you want to get stream online notifications for.

Stream Offline Condition

Name Type Required? Description
broadcaster_user_id string yes The broadcaster user ID you want to get stream offline notifications for.

User Authorization Revoke Condition

Name Type Required? Description
client_id string yes Your application’s client id. The provided client_id must match the client id in the application access token.

User Update Condition

Name Type Required? Description
user_id string yes The user ID for the user you want update notifications for.

Events

Channel Ban Event

Name Type Description
user_id string The user ID for the user who was banned on the specified channel.
user_login string The user login for the user who was banned on the specified channel.
user_name string The user display name for the user who was banned on the specified channel.
broadcaster_user_id string The requested broadcaster ID.
broadcaster_user_login string The requested broadcaster login.
broadcaster_user_name string The requested broadcaster display name.
moderator_user_id string The user ID of the issuer of the ban.
moderator_user_login string The user login of the issuer of the ban.
moderator_user_name string The user name of the issuer of the ban.
reason string The reason behind the ban.
ends_at string Will be null if permanent ban. If it is a timeout, this field shows when the timeout will end.
is_permanent boolean Indicates whether the ban is permanent (true) or a timeout (false). If true, ends_at will be null.

Channel Subscribe Event

Name Type Description
user_id string The user ID for the user who subscribed to the specified channel.
user_login string The user login for the user who subscribed to the specified channel.
user_name string The user display name for the user who subscribed to the specified channel.
broadcaster_user_id string The requested broadcaster ID.
broadcaster_user_login string The requested broadcaster login.
broadcaster_user_name string The requested broadcaster display name.
tier string The tier of the subscription. Valid values are 1000, 2000, and 3000.
is_gift boolean Whether the subscription is a gift.

Channel Cheer Event

Name Type Description
is_anonymous boolean Whether the user cheered anonymously or not.
user_id string The user ID for the user who cheered on the specified channel. This is null if is_anonymous is true.
user_login string The user login for the user who cheered on the specified channel. This is null if is_anonymous is true.
user_name string The user display name for the user who cheered on the specified channel. This is null if is_anonymous is true.
broadcaster_user_id string The requested broadcaster ID.
broadcaster_user_login string The requested broadcaster login.
broadcaster_user_name string The requested broadcaster display name.
message string The message sent with the cheer.
bits int The number of bits cheered.

Channel Update Event

Name Type Description
broadcaster_user_id string The broadcaster’s user ID.
broadcaster_user_login string The broadcaster’s user login.
broadcaster_user_name string The broadcaster’s user display name.
title string The channel’s stream title.
language string The channel’s broadcast language.
category_id string The channel’s category ID.
category_name string The category name.
is_mature boolean A boolean identifying whether the channel is flagged as mature. Valid values are true and false.

Channel Unban Event

Name Type Description
user_id string The user id for the user who was unbanned on the specified channel.
user_login string The user login for the user who was unbanned on the specified channel.
user_name string The user display name for the user who was unbanned on the specified channel.
broadcaster_user_id string The requested broadcaster ID.
broadcaster_user_login string The requested broadcaster login.
broadcaster_user_name string The requested broadcaster display name.
moderator_user_id string The user ID of the issuer of the unban.
moderator_user_login string The user login of the issuer of the unban.
moderator_user_name string The user name of the issuer of the unban.

Channel Follow Event

Name Type Description
user_id string The user ID for the user now following the specified channel.
user_login string The user login for the user now following the specified channel.
user_name string The user display name for the user now following the specified channel.
broadcaster_user_id string The requested broadcaster ID.
broadcaster_user_login string The requested broadcaster login.
broadcaster_user_name string The requested broadcaster display name.
followed_at string RFC3339 timestamp of when the follow occurred.

Channel Raid Event

Name Type Description
from_broadcaster_user_id string The broadcaster ID that created the raid.
from_broadcaster_user_login string The broadcaster login that created the raid.
from_broadcaster_user_name string The broadcaster display name that created the raid.
to_broadcaster_user_id string The broadcaster ID that received the raid.
to_broadcaster_user_login string The broadcaster login that received the raid.
to_broadcaster_user_name string The broadcaster display name that received the raid.
viewers int The number of viewers in the raid.

Channel Points Custom Reward Add Event

Name Type Description
id string The reward identifier.
broadcaster_user_id string The requested broadcaster ID.
broadcaster_user_login string The requested broadcaster login.
broadcaster_user_name string The requested broadcaster display name.
is_enabled boolean Is the reward currently enabled. If false, the reward won’t show up to viewers.
is_paused boolean Is the reward currently paused. If true, viewers can’t redeem.
is_in_stock boolean Is the reward currently in stock. If false, viewers can’t redeem.
title string The reward title.
cost int The reward cost.
prompt string The reward description.
is_user_input_required boolean Does the viewer need to enter information when redeeming the reward.
should_redemptions_skip_request_queue boolean Should redemptions be set to fulfilled status immediately when redeemed and skip the request queue instead of the normal unfulfilled status.
max_per_stream  max_per_stream  Whether a maximum per stream is enabled and what the maximum is.
max_per_user_per_stream  max_per_user_per_stream  Whether a maximum per user per stream is enabled and what the maximum is.
background_color string Custom background color for the reward. Format: Hex with # prefix. Example: #FA1ED2.
image  image  Set of custom images of 1x, 2x and 4x sizes for the reward. Can be null if no images have been uploaded.
default_image  image  Set of default images of 1x, 2x and 4x sizes for the reward.
global_cooldown  global_cooldown  Whether a cooldown is enabled and what the cooldown is in seconds.
cooldown_expires_at string Timestamp of the cooldown expiration. null if the reward isn’t on cooldown.
redemptions_redeemed_current_stream int The number of redemptions redeemed during the current live stream. Counts against the max_per_stream limit. null if the broadcasters stream isn’t live or max_per_stream isn’t enabled.

Channel Points Custom Reward Update Event

Name Type Description
id string The reward identifier.
broadcaster_user_id string The requested broadcaster ID.
broadcaster_user_login string The requested broadcaster login.
broadcaster_user_name string The requested broadcaster display name.
is_enabled boolean Is the reward currently enabled. If false, the reward won’t show up to viewers.
is_paused boolean Is the reward currently paused. If true, viewers can’t redeem.
is_in_stock boolean Is the reward currently in stock. If false, viewers can’t redeem.
title string The reward title.
cost int The reward cost.
prompt string The reward description.
is_user_input_required boolean Does the viewer need to enter information when redeeming the reward.
should_redemptions_skip_request_queue boolean Should redemptions be set to fulfilled status immediately when redeemed and skip the request queue instead of the normal unfulfilled status.
max_per_stream  max_per_stream  Whether a maximum per stream is enabled and what the maximum is.
max_per_user_per_stream  max_per_user_per_stream  Whether a maximum per user per stream is enabled and what the maximum is.
background_color string Custom background color for the reward. Format: Hex with # prefix. Example: #FA1ED2.
image  image  Set of custom images of 1x, 2x and 4x sizes for the reward. Can be null if no images have been uploaded.
default_image  image  Set of default images of 1x, 2x and 4x sizes for the reward.
global_cooldown  global_cooldown  Whether a cooldown is enabled and what the cooldown is in seconds.
cooldown_expires_at string Timestamp of the cooldown expiration. null if the reward isn’t on cooldown.
redemptions_redeemed_current_stream int The number of redemptions redeemed during the current live stream. Counts against the max_per_stream limit. null if the broadcasters stream isn’t live or max_per_stream isn’t enabled.

Channel Points Custom Reward Remove Event

Name Type Description
id string The reward identifier.
broadcaster_user_id string The requested broadcaster ID.
broadcaster_user_login string The requested broadcaster login.
broadcaster_user_name string The requested broadcaster display name.
is_enabled boolean Is the reward currently enabled. If false, the reward won’t show up to viewers.
is_paused boolean Is the reward currently paused. If true, viewers can’t redeem.
is_in_stock boolean Is the reward currently in stock. If false, viewers can’t redeem.
title string The reward title.
cost int The reward cost.
prompt string The reward description.
is_user_input_required boolean Does the viewer need to enter information when redeeming the reward.
should_redemptions_skip_request_queue boolean Should redemptions be set to fulfilled status immediately when redeemed and skip the request queue instead of the normal unfulfilled status.
max_per_stream  max_per_stream  Whether a maximum per stream is enabled and what the maximum is.
max_per_user_per_stream  max_per_user_per_stream  Whether a maximum per user per stream is enabled and what the maximum is.
background_color string Custom background color for the reward. Format: Hex with # prefix. Example: #FA1ED2.
image  image  Set of custom images of 1x, 2x and 4x sizes for the reward. Can be null if no images have been uploaded.
default_image  image  Set of default images of 1x, 2x and 4x sizes for the reward.
global_cooldown  global_cooldown  Whether a cooldown is enabled and what the cooldown is in seconds.
cooldown_expires_at string Timestamp of the cooldown expiration. null if the reward isn’t on cooldown.
redemptions_redeemed_current_stream int The number of redemptions redeemed during the current live stream. Counts against the max_per_stream limit. null if the broadcasters stream isn’t live or max_per_stream isn’t enabled.

Channel Points Custom Reward Redemption Add Event

Name Type Description
id string The redemption identifier.
broadcaster_user_id string The requested broadcaster ID.
broadcaster_user_login string The requested broadcaster login.
broadcaster_user_name string The requested broadcaster display name.
user_id string User ID of the user that redeemed the reward.
user_login string Login of the user that redeemed the reward.
user_name string Display name of the user that redeemed the reward.
user_input string The user input provided. Empty string if not provided.
status string Defaults to unfulfilled. Possible values are unknown, unfulfilled, fulfilled, and canceled.
reward  reward  Basic information about the reward that was redeemed, at the time it was redeemed.
redeemed_at string RFC3339 timestamp of when the reward was redeemed.

Channel Points Custom Reward Redemption Update Event

Name Type Description
id string The redemption identifier.
broadcaster_user_id string The requested broadcaster ID.
broadcaster_user_login string The requested broadcaster login.
broadcaster_user_name string The requested broadcaster display name.
user_id string User ID of the user that redeemed the reward.
user_login string Login of the user that redeemed the reward.
user_name string Display name of the user that redeemed the reward.
user_input string The user input provided. Empty string if not provided.
status string Will be fulfilled or canceled. Possible values are unknown, unfulfilled, fulfilled, and canceled.
reward  reward  Basic information about the reward that was redeemed, at the time it was redeemed.
redeemed_at string RFC3339 timestamp of when the reward was redeemed.

Hype Train Begin Event

Name Type Description
broadcaster_user_id string The requested broadcaster ID.
broadcaster_user_login string The requested broadcaster login.
broadcaster_user_name string The requested broadcaster display name.
total int Total points contributed to the hype train.
progress int The number of points contributed to the hype train at the current level.
goal int The number of points required to reach the next level.
top_contributions  top_contributions  The contributors with the most points contributed.
last_contribution  last_contribution  The most recent contribution.
started_at string The timestamp at which the hype train started.
expires_at string The time at which the hype train expires. The expiration is extended when the hype train reaches a new level.

Hype Train Progress Event

Name Type Description
broadcaster_user_id string The requested broadcaster ID.
broadcaster_user_login string The requested broadcaster login.
broadcaster_user_name string The requested broadcaster display name.
level int Current level of hype train event.
total int Total points contributed to the hype train.
progress int The number of points contributed to the hype train at the current level.
goal int The number of points required to reach the next level.
top_contributions  top_contributions  The contributors with the most points contributed.
last_contribution  last_contribution  The most recent contribution.
started_at string The timestamp at which the hype train started.
expires_at string The time at which the hype train expires. The expiration is extended when the hype train reaches a new level.

Hype Train End Event

Name Type Description
broadcaster_user_id string The requested broadcaster ID.
broadcaster_user_login string The requested broadcaster login.
broadcaster_user_name string The requested broadcaster display name.
level int Current level of hype train event.
total int Total points contributed to the hype train.
top_contributions  top_contributions  The contributors with the most points contributed.
started_at string The timestamp at which the hype train started.
ended_at string The timestamp at which the hype train ended.
cooldown_ends_at string The timestamp at which the hype train cooldown ends so that the next hype train can start.

Stream Online Event

Name Type Description
id string The id of the stream.
broadcaster_user_id string The broadcaster’s user id.
broadcaster_user_login string The broadcaster’s user login.
broadcaster_user_name string The broadcaster’s user display name.
type string The stream type. Valid values are: live, playlist, watch_party, premiere, rerun.
started_at string The timestamp at which the stream went online at.

Stream Offline Event

Name Type Description
broadcaster_user_id string The broadcaster’s user id.
broadcaster_user_login string The broadcaster’s user login.
broadcaster_user_name string The broadcaster’s user display name.

User Authorization Revoke Event

Name Type Description
client_id string The client_id of the application with revoked user access.
user_id string The user id for the user who has revoked authorization for your client id.
user_login string The user login for the user who has revoked authorization for your client id. This is null if the user no longer exists.
user_name string The user display name for the user who has revoked authorization for your client id. This is null if the user no longer exists.

User Update Event

Name Type Description
user_id string The user’s user id.
user_login string The user’s user login.
user_name string The user’s user display name.
email string The user’s email. Only included if you have the user:read:emailscope for the user.
description string The user’s description.

Global Cooldown

Name Type Description
is_enabled boolean Is the setting enabled.
seconds int The cooldown in seconds.

Image

Name Type Description
url_1x string URL for the image at 1x size.
url_2x string URL for the image at 2x size.
url_4x string URL for the image at 4x size.

Last Contribution

Name Type Description
user_id string The ID of the user.
user_login string The login of the user.
user_name string The display name of the user.
type string Type of contribution. Valid values include bits, subscription.
total int The total contributed.

Max Per Stream

Name Type Description
is_enabled boolean Is the setting enabled.
value int The max per stream limit.

Max Per User Per Stream

Name Type Description
is_enabled boolean Is the setting enabled.
value int The max per user per stream limit.

Reward

Name Type Description
id string The reward identifier.
title string The reward name.
cost int The reward cost.
prompt string The reward description.

Subscription

Name Type Description
id string Your client ID.
type string The notification’s subscription type.
version string The version of the subscription.
status string The status of the subscription.
condition  condition  Subscription-specific parameters.
created_at string The time the notification was created.

Top Contributions

An array of objects that describe a user, the type of their hype train contribution, and their total contribution amount. Contains a maximum of two user objects: one for the top bits contributor and one for the top subscriptions contributor (this includes gifted subscriptions).

Name Type Description
user_id string The ID of the user.
user_login string The login of the user.
user_name string The display name of the user.
type string Type of contribution. Valid values include bits, subscription.
total int The total contributed.

Transport

Name Type Required? Description
method string yes The transport method. Supported values: webhook.
callback string yes The callback URL where the notification should be sent.
secret string yes The secret used for verifying a signature.
Docs Status Support Showcase Blog