Contents

Subscription Types

Subscription Type Name Version Description
Channel Update channel.update 1 A broadcaster updates their channel properties e.g., category, title, mature flag, broadcast, or language.
Channel Follow channel.follow 1 A specified channel receives a follow.
Channel Subscribe channel.subscribe 1 A notification when a specified channel receives a subscriber. This does not include resubscribes.
Channel Cheer channel.cheer 1 A user cheers on the specified channel.
Channel Raid channel.raid 1 A broadcaster raids another broadcaster’s channel.
Channel Ban channel.ban 1 A viewer is banned from the specified channel.
Channel Unban channel.unban 1 A viewer is unbanned from the specified channel.
Channel Moderator Add channel.moderator.add 1 Moderator privileges were added to a user on a specified channel.
Channel Moderator Remove channel.moderator.remove 1 Moderator privileges were removed from a user on a specified channel.
Channel Points Custom Reward Add channel.channel_points_custom_reward.add 1 A custom channel points reward has been created for the specified channel.
Channel Points Custom Reward Update channel.channel_points_custom_reward.update 1 A custom channel points reward has been updated for the specified channel.
Channel Points Custom Reward Remove channel.channel_points_custom_reward.remove 1 A custom channel points reward has been removed from the specified channel.
Channel Points Custom Reward Redemption Add channel.channel_points_custom_reward_redemption.add 1 A viewer has redeemed a custom channel points reward on the specified channel.
Channel Points Custom Reward Redemption Update channel.channel_points_custom_reward_redemption.update 1 A redemption of a channel points custom reward has been updated for the specified channel.
Hype Train Begin channel.hype_train.begin 1 A hype train begins on the specified channel.
Hype Train Progress channel.hype_train.progress 1 A hype train makes progress on the specified channel.
Hype Train End channel.hype_train.end 1 A hype train ends on the specified channel.
Stream Online stream.online 1 The specified broadcaster starts a stream.
Stream Offline stream.offline 1 The specified broadcaster stops a stream.
User Authorization Revoke user.authorization.revoke 1 A user’s authorization has been revoked for your client id.
User Update user.update 1 A user has updated their account.

Channel Subscriptions

channel.update

The channel.update subscription type sends notifications when a broadcaster updates the category, title, mature flag, or broadcast language for their channel.

Authorization

No authorization required.

Channel Update Request Body

Name Type Required? Description
type string yes The subscription type name: channel.update.
version string yes The subscription type version: 1.
condition  condition  yes Pass in the broadcaster_user_id for the channel you want updates for.
transport  transport  yes Transport-specific parameters.

Channel Update Webhook Example

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

Channel Update Notification Payload

Name Type Description
subscription  subscription  Metadata about the subscription.
event  event  Returns the user ID, user name, title, language, category ID, category name, and mature flag setting for the given broadcaster.

Channel Update Notification Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.update",
        "version": "1",
        "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.123Z"
    },
    "event": {
        "broadcaster_user_id": "1337",
        "broadcaster_user_login": "cool_user",
        "broadcaster_user_name": "Cool_User",
        "title": "Best Stream Ever",
        "language": "en",
        "category_id": "21779",
        "category_name": "Fortnite",
        "is_mature": false
    }
}

channel.follow

The channel.follow subscription type sends a notification when a specified channel receives a follow.

Authorization

No authorization required.

Channel Follow Request Body

Name Type Required? Description
type string yes The subscription type name: channel.follow.
version string yes The subscription type version: 1.
condition  condition  yes Subscription-specific parameters.
transport  transport  yes Transport-specific parameters.

Channel Follow Webhook Example

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

Channel Follow Notification Payload

Name Type Description
subscription  subscription  Metadata about the subscription.
event  event  The event information. Contains the user ID and user name of the follower and the broadcaster user ID and broadcaster user name.

Channel Follow Webhook Notification Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.follow",
        "version": "1",
        "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.123Z"
    },
    "event": {
        "user_id": "1234",
        "user_login": "cool_user",
        "user_name": "Cool_User",
        "broadcaster_user_id": "1337",
        "broadcaster_user_login": "cooler_user",
        "broadcaster_user_name": "Cooler_User",
        "followed_at": "2020-07-15T18:16:11.17106713Z"
    }
}

channel.subscribe

The channel.subscribe subscription type sends a notification when a specified channel receives a subscriber. This does not include resubscribes.

Authorization

Must have channel:read:subscriptions scope.

Channel Subscribe Request Body

Name Type Required? Description
type string yes The subscription type name: channel.subscribe.
version string yes The subscription type version: 1.
condition  condition  yes Subscription-specific parameters.
transport  transport  yes Transport-specific parameters.

Channel Subscribe Webhook Example

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

Channel Subscribe Notification Payload

Name Type Description
subscription  subscription  Metadata about the subscription.
event  event  The event information. Contains the user ID and user name of the subscriber, the broadcaster user ID and broadcaster user name, and whether the subscription is a gift.

Channel Subscribe Webhook Notification Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.subscribe",
        "version": "1",
        "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.123Z"
    },
    "event": {
        "user_id": "1234",
        "user_login": "cool_user",
        "user_name": "Cool_User",
        "broadcaster_user_id": "1337",
        "broadcaster_user_login": "cooler_user",
        "broadcaster_user_name": "Cooler_User",
        "tier": "1000",
        "is_gift": false
    }
}

channel.cheer

The channel.cheer subscription type sends a notification when a user cheers on the specified channel.

Authorization

Must have bits:read scope.

Channel Cheer Request Body

Name Type Required? Description
type string yes The subscription type name: channel.cheer.
version string yes The subscription type version: 1.
condition  condition  yes Subscription-specific parameters. Pass in the broadcaster user ID for the channel you want to receive cheer notifications for.
transport  transport  yes Transport-specific parameters.

Channel Cheer Webhook Example

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

Channel Cheer Notification Payload

Name Type Description
subscription  subscription  Metadata about the subscription.
event  event  The event information. Contains the user ID and user name of the cheering user along with the broadcaster user id and broadcaster user name.

Channel Cheer Notification Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.cheer",
        "version": "1",
        "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.123Z"
    },
    "event": {
        "is_anonymous": false,
        "user_id": "1234",          // null if is_anonymous=true
        "user_login": "cool_user",  // null if is_anonymous=true
        "user_name": "Cool_User",   // null if is_anonymous=true
        "broadcaster_user_id": "1337",
        "broadcaster_user_login": "cooler_user",
        "broadcaster_user_name": "Cooler_User",
        "message": "pogchamp",
        "bits": 1000
    }
}

channel.raid

The channel.raid subscription type sends a notification when a broadcaster raids another broadcaster’s channel.

Authorization

No authorization required.

Channel Raid Request Body

Name Type Required? Description
type string yes The subscription type name: channel.raid.
version string yes The subscription type version: 1.
condition  condition  yes Subscription-specific parameters. Pass in either from_broadcaster_user_id or to_broadcaster_user_id. If you pass in both parameters you will receive an error.
transport  transport  yes Transport-specific parameters.

Channel Raid Webhook Example

{
    "type": "channel.raid",
    "version": "1",
    "condition": {
        "to_broadcaster_user_id": "1337" // could provide from_broadcaster_user_id instead
    },
    "transport": {
        "method": "webhook",
        "callback": "https://example.com/webhooks/callback",
        "secret": "s3cRe7"
    }
}

Channel Raid Notification Payload

Name Type Description
subscription  subscription  Metadata about the subscription.
event  event  The event information. Contains the from and to broadcaster information along with the number of viewers in the raid. Will only notify for raids that appear in chat.

Channel Raid Notification Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.raid",
        "version": "1",
        "status": "enabled",
        "cost": 0,
        "condition": {
            "to_broadcaster_user_id": "1337"
        },
         "transport": {
            "method": "webhook",
            "callback": "https://example.com/webhooks/callback"
        },
        "created_at": "2019-11-16T10:11:12.123Z"
    },
    "event": {
        "from_broadcaster_user_id": "1234",
        "from_broadcaster_user_login": "cool_user",
        "from_broadcaster_user_name": "Cool_User",
        "to_broadcaster_user_id": "1337",
        "to_broadcaster_user_login": "cooler_user",
        "to_broadcaster_user_name": "Cooler_User",
        "viewers": 9001
    }
}

channel.ban

The channel.ban subscription type sends a notification when a viewer is timed out or banned from the specified channel.

Authorization

Must have channel:moderate scope.

Channel Ban Request Body

Name Type Required? Description
type string yes The subscription type name: channel.ban.
version string yes The subscription type version: 1.
condition  condition  yes Subscription-specific parameters. Pass in the broadcaster user ID for the channel you want to receive ban notifications for.
transport  transport  yes Transport-specific parameters.

Channel Ban Webhook Example

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

Channel Ban Notification Payload

Name Type Description
subscription  subscription  Metadata about the subscription.
event  event  The event information. Will notify on timeouts as well as bans. Contains the user ID and user name of the banned user, the broadcaster user ID and broadcaster user name, the user ID and user name of the moderator who issued the ban/timeout, the reason, and expiration time if it is a timeout.

Channel Ban Notification Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.ban",
        "version": "1",
        "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.123Z"
    },
    "event": {
        "user_id": "1234",
        "user_login": "cool_user",
        "user_name": "Cool_User",
        "broadcaster_user_id": "1337",
        "broadcaster_user_login": "cooler_user",
        "broadcaster_user_name": "Cooler_User",
        "moderator_user_id": "1339",
        "moderator_user_login": "mod_user",
        "moderator_user_name": "Mod_User",
        "reason": "Offensive language",
        "ends_at": "2020-07-15T18:16:11.17106713Z",
        "is_permanent": false
    }
}

channel.unban

The channel.unban subscription type sends a notification when a viewer is unbanned from the specified channel.

Authorization

Must have channel:moderate scope.

Channel Unban Request Body

Name Type Required? Description
type string yes The subscription type name: channel.unban.
version string yes The subscription type version: 1.
condition  condition  yes Subscription-specific parameters. Pass in the broadcaster user ID for the channel you want to receive unban notifications for.
transport  transport  yes Transport-specific parameters.

Channel Unban Webhook Example

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

Channel Unban Notification Payload

Name Type Description
subscription  subscription  Metadata about the subscription.
event  event  The event information. Contains the user ID and user name of the unbanned user, the broadcaster user id and broadcaster user name, as well as the user ID and user name of the moderator who issued the unban.

Channel Unban Notification Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.unban",
        "version": "1",
        "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.123Z"
    },
    "event": {
        "user_id": "1234",
        "user_login": "cool_user",
        "user_name": "Cool_User",
        "broadcaster_user_id": "1337",
        "broadcaster_user_login": "cooler_user",
        "broadcaster_user_name": "Cooler_User",
         "moderator_user_id": "1339",
        "moderator_user_login": "mod_user",
        "moderator_user_name": "Mod_User"
    }
}

channel.moderator.add

The channel.moderator.add subscription type sends a notification when a user is given moderator privileges on a specified channel.

Authorization

Must have moderation:read scope.

Channel Moderator Add Request Body

Name Type Required? Description
type string yes The subscription type name: channel.moderator.add.
version string yes The subscription type version: 1.
condition  condition  yes Subscription-specific parameters. Pass in the broadcaster user ID for the channel you want to receive moderator addition notifications for.
transport  transport  yes Transport-specific parameters.

Channel Moderator Add Example

{
    "type": "channel.moderator.add",
    "version": "1",
    "condition": {
        "broadcaster_user_id": "1337"
    },
    "transport": {
        "method": "webhook",
        "callback": "https://example.com/webhooks/callback",
        "secret": "s3cRe7"
    }
}

Channel Moderator Add Notification Payload

Name Type Description
subscription  subscription  Metadata about the subscription.
event  event  The event information. Contains user information of the new moderator as well as broadcaster information of the channel the event occurred on.

Channel Moderator Add Notification Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.moderator.add",
        "version": "1",
        "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.123Z"
    },
    "event": {
        "user_id": "1234",
        "user_login": "mod_user",
        "user_name": "Mod_User",
        "broadcaster_user_id": "1337",
        "broadcaster_user_login": "cooler_user",
        "broadcaster_user_name": "Cooler_User"
    }
}

channel.moderator.remove

The channel.moderator.remove subscription type sends a notification when a user has moderator privileges removed on a specified channel.

Authorization

Must have moderation:read scope.

Channel Moderator Remove Request Body

Name Type Required? Description
type string yes The subscription type name: channel.moderator.remove.
version string yes The subscription type version: 1.
condition  condition  yes Subscription-specific parameters. Pass in the broadcaster user ID for the channel you want to receive moderator removal notifications for.
transport  transport  yes Transport-specific parameters.

Channel Moderator Remove Example

{
    "type": "channel.moderator.remove",
    "version": "1",
    "condition": {
        "broadcaster_user_id": "1337"
    },
    "transport": {
        "method": "webhook",
        "callback": "https://example.com/webhooks/callback",
        "secret": "s3cRe7"
    }
}

Channel Moderator Remove Notification Payload

Name Type Description
subscription  subscription  Metadata about the subscription.
event  event  The event information. Contains user information of the old moderator as well as broadcaster information of the channel the event occurred on.

Channel Moderator Remove Notification Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.moderator.remove",
        "version": "1",
        "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.123Z"
    },
    "event": {
        "user_id": "1234",
        "user_login": "not_mod_user",
        "user_name": "Not_Mod_User",
        "broadcaster_user_id": "1337",
        "broadcaster_user_login": "cooler_user",
        "broadcaster_user_name": "Cooler_User"
    }
}

channel.channel_points_custom_reward.add

The channel.channel_points_custom_reward.add subscription type sends a notification when a custom channel points reward has been created for the specified channel.

Authorization

Must have channel:read:redemptions or channel:manage:redemptions scope.

Channel Points Custom Reward Add Request Body

Name Type Required? Description
type string yes The subscription type name: channel.channel_points_custom_reward.add.
version string yes The subscription type version: 1.
condition  condition  yes Subscription-specific parameters. Pass in the broadcaster user ID for the channel you want to receive channel points customer reward add notifications for.
transport  transport  yes Transport-specific parameters.

Channel Points Custom Reward Add Webhook Example

{
    "type": "channel.channel_points_custom_reward.add",
    "version": "1",
    "condition": {
        "broadcaster_user_id": "1337"
    },
    "transport": {
        "method": "webhook",
        "callback": "https://example.com/webhooks/callback",
        "secret": "s3cRe7"
    }
}

Channel Points Custom Reward Add Notification Payload

Name Type Description
subscription  subscription  Metadata about the subscription.
event  event  The event information. Contains data about the custom reward added to the broadcaster’s channel.

Channel Points Custom Reward Add Notification Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.channel_points_custom_reward.add",
        "version": "1",
        "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.123Z"
    },
    "event": {
        "id": "9001",
        "broadcaster_user_id": "1337",
        "broadcaster_user_login": "cool_user",
        "broadcaster_user_name": "Cool_User",
        "is_enabled": true,
        "is_paused": false,
        "is_in_stock": true,
        "title": "Cool Reward",
        "cost": 100,
        "prompt": "reward prompt",
        "is_user_input_required": true,
        "should_redemptions_skip_request_queue": false,
        "cooldown_expires_at": null,
        "redemptions_redeemed_current_stream": null,
        "max_per_stream": {
            "is_enabled": true,
            "value": 1000
        },
        "max_per_user_per_stream": {
            "is_enabled": true,
            "value": 1000
        },
        "global_cooldown": {
            "is_enabled": true,
            "seconds": 1000
        },
        "background_color": "#FA1ED2",
        "image": {
            "url_1x": "https://static-cdn.jtvnw.net/image-1.png",
            "url_2x": "https://static-cdn.jtvnw.net/image-2.png",
            "url_4x": "https://static-cdn.jtvnw.net/image-4.png"
        },
        "default_image": {
            "url_1x": "https://static-cdn.jtvnw.net/default-1.png",
            "url_2x": "https://static-cdn.jtvnw.net/default-2.png",
            "url_4x": "https://static-cdn.jtvnw.net/default-4.png"
        }
    }
}

channel.channel_points_custom_reward.update

The channel.channel_points_custom_reward.update subscription type sends a notification when a custom channel points reward has been updated for the specified channel.

Authorization

Must have channel:read:redemptions or channel:manage:redemptions scope.

Channel Points Custom Reward Update Request Body

Name Type Required? Description
type string yes The subscription type name: channel.channel_points_custom_reward.update.
version string yes The subscription type version: 1.
condition  condition  yes Subscription-specific parameters. Pass in the broadcaster user ID for the channel you want to receive channel points custom reward update notifications for. You can optionally pass in a reward id to only receive notifications for a specific reward.
transport  transport  yes Transport-specific parameters.

Channel Points Custom Reward Update Webhook Example

{
    "type": "channel.channel_points_custom_reward.update",
    "version": "1",
    "condition": {
        "broadcaster_user_id": "1337",
        "reward_id": "9001" // optional to only get notifications for a specific reward
    },
    "transport": {
        "method": "webhook",
        "callback": "https://example.com/webhooks/callback",
        "secret": "s3cRe7"
    }
}

Channel Points Custom Reward Update Notification Payload

Name Type Description
subscription  subscription  Metadata about the subscription.
event  event  The event information. Contains data about the custom reward updated on the broadcaster’s channel.

Channel Points Custom Reward Update Notification Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.channel_points_custom_reward.update",
        "version": "1",
        "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.123Z"
    },
    "event": {
        "id": "9001",
        "broadcaster_user_id": "1337",
        "broadcaster_user_login": "cool_user",
        "broadcaster_user_name": "Cool_User",
        "is_enabled": true,
        "is_paused": false,
        "is_in_stock": true,
        "title": "Cool Reward",
        "cost": 100,
        "prompt": "reward prompt",
        "is_user_input_required": true,
        "should_redemptions_skip_request_queue": false,
        "cooldown_expires_at": "2019-11-16T10:11:12.123Z",
        "redemptions_redeemed_current_stream": 123,
        "max_per_stream": {
            "is_enabled": true,
            "value": 1000
        },
        "max_per_user_per_stream": {
            "is_enabled": true,
            "value": 1000
        },
        "global_cooldown": {
            "is_enabled": true,
            "seconds": 1000
        },
        "background_color": "#FA1ED2",
        "image": {
            "url_1x": "https://static-cdn.jtvnw.net/image-1.png",
            "url_2x": "https://static-cdn.jtvnw.net/image-2.png",
            "url_4x": "https://static-cdn.jtvnw.net/image-4.png"
        },
        "default_image": {
            "url_1x": "https://static-cdn.jtvnw.net/default-1.png",
            "url_2x": "https://static-cdn.jtvnw.net/default-2.png",
            "url_4x": "https://static-cdn.jtvnw.net/default-4.png"
        }
    }
}

channel.channel_points_custom_reward.remove

The channel.channel_points_custom_reward.remove subscription type sends a notification when a custom channel points reward has been removed from the specified channel.

Authorization

Must have channel:read:redemptions or channel:manage:redemptions scope.

Channel Points Custom Reward Remove Request Body

Name Type Required? Description
type string yes The subscription type name: channel.channel_points_custom_reward.remove.
version string yes The subscription type version: 1.
condition  condition  yes Subscription-specific parameters. Pass in the broadcaster user ID for the channel you want to receive channel points custom reward remove notifications for. You can optionally pass in a reward ID to only receive notifications for a specific reward.
transport  transport  yes Transport-specific parameters.

Channel Points Custom Reward Remove Webhook Example

{
    "type": "channel.channel_points_custom_reward.remove",
    "version": "1",
    "condition": {
        "broadcaster_user_id": "1337",
        "reward_id": "9001" // optional to only get notifications for a specific reward
    },
    "transport": {
        "method": "webhook",
        "callback": "https://example.com/webhooks/callback",
        "secret": "s3cRe7"
    }
}

Channel Points Custom Reward Remove Notification Payload

Name Type Description
subscription  subscription  Subscription information.
event  event  The event information. Contains data about the custom reward removed from the broadcaster’s channel.

Channel Points Custom Reward Remove Notification Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.channel_points_custom_reward.remove",
        "version": "1",
        "status": "enabled",
        "cost": 0,
        "condition": {
            "broadcaster_user_id": "1337",
            "reward_id": 12345
        },
         "transport": {
            "method": "webhook",
            "callback": "https://example.com/webhooks/callback"
        },
        "created_at": "2019-11-16T10:11:12.123Z"
    },
    "event": {
        "id": "9001",
        "broadcaster_user_id": "1337",
        "broadcaster_user_login": "cool_user",
        "broadcaster_user_name": "Cool_User",
        "is_enabled": true,
        "is_paused": false,
        "is_in_stock": true,
        "title": "Cool Reward",
        "cost": 100,
        "prompt": "reward prompt",
        "is_user_input_required": true,
        "should_redemptions_skip_request_queue": false,
        "cooldown_expires_at": "2019-11-16T10:11:12.123Z",
        "redemptions_redeemed_current_stream": 123,
        "max_per_stream": {
            "is_enabled": true,
            "value": 1000
        },
        "max_per_user_per_stream": {
            "is_enabled": true,
            "value": 1000
        },
        "global_cooldown": {
            "is_enabled": true,
            "seconds": 1000
        },
        "background_color": "#FA1ED2",
        "image": {
            "url_1x": "https://static-cdn.jtvnw.net/image-1.png",
            "url_2x": "https://static-cdn.jtvnw.net/image-2.png",
            "url_4x": "https://static-cdn.jtvnw.net/image-4.png"
        },
        "default_image": {
            "url_1x": "https://static-cdn.jtvnw.net/default-1.png",
            "url_2x": "https://static-cdn.jtvnw.net/default-2.png",
            "url_4x": "https://static-cdn.jtvnw.net/default-4.png"
        }
    }
}

channel.channel_points_custom_reward_redemption.add

The channel.channel_points_custom_reward_redemption.add subscription type sends a notification when a viewer has redeemed a custom channel points reward on the specified channel.

Authorization

Must have channel:read:redemptions or channel:manage:redemptions scope.

Channel Points Custom Reward Redemption Add Request Body

Name Type Required? Description
type string yes The subscription type name: channel.channel_points_custom_reward_redemption.add.
version string yes The subscription type version: 1.
condition  condition  yes Subscription-specific parameters. Pass in the broadcaster user ID for the channel you want to receive channel points custom reward redemption notifications for. You can optionally pass in a reward id to only receive notifications for a specific reward.
transport  transport  yes Transport-specific parameters.

Channel Points Custom Reward Redemption Add Webhook Example

{
    "type": "channel.channel_points_custom_reward_redemption.add",
    "version": "1",
    "condition": {
        "broadcaster_user_id": "1337",
        "reward_id": "9001" // optional to only get notifications for a specific reward
    },
    "transport": {
        "method": "webhook",
        "callback": "https://example.com/webhooks/callback",
        "secret": "s3cRe7"
    }
}

Channel Points Custom Reward Redemption Add Notification Payload

Name Type Description
subscription  subscription  Subscription information.
event  event  The event information. Contains data about the redemption of the custom reward on the broadcaster’s channel.

Channel Points Custom Reward Redemption Add Notification Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.channel_points_custom_reward_redemption.add",
        "version": "1",
        "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.123Z"
    },
    "event": {
        "id": "1234",
        "broadcaster_user_id": "1337",
        "broadcaster_user_login": "cool_user",
        "broadcaster_user_name": "Cool_User",
        "user_id": "9001",
        "user_login": "cooler_user",
        "user_name": "Cooler_User",
        "user_input": "pogchamp",
        "status": "unfulfilled",
        "reward": {
            "id": "9001",
            "title": "title",
            "cost": 100,
            "prompt": "reward prompt"
        },
        "redeemed_at": "2020-07-15T17:16:03.17106713Z"
    }
}

channel.channel_points_custom_reward_redemption.update

The channel.channel_points_custom_reward_redemption.update subscription type sends a notification when a redemption of a channel points custom reward has been updated for the specified channel.

Authorization

Must have channel:read:redemptions or channel:manage:redemptions scope.

Channel Points Custom Reward Redemption Update Request Body

Name Type Required? Description
type string yes The subscription type name: channel.channel_points_custom_reward_redemption.update.
version string yes The subscription type version: 1.
condition  condition  yes Subscription-specific parameters. Pass in the broadcaster user ID for the channel you want to receive channel points custom reward redemption update notifications for. You can optionally pass in a reward id to only receive notifications for a specific reward.
transport  transport  yes Transport-specific parameters.

Channel Points Custom Reward Redemption Update Webhook Example

{
    "type": "channel.channel_points_custom_reward_redemption.update",
    "version": "1",
    "condition": {
        "broadcaster_user_id": "1337",
        "reward_id": "9001" // optional to only get notifications for a specific reward
    },
    "transport": {
        "method": "webhook",
        "callback": "https://example.com/webhooks/callback",
        "secret": "s3cRe7"
    }
}

Channel Points Custom Reward Redemption Update Notification Payload

Name Type Description
subscription  subscription  Subscription information.
event  event  The event information. Contains data about the custom reward redemption update from the broadcaster’s channel.

Channel Points Custom Reward Redemption Update Notification Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.channel_points_custom_reward_redemption.update",
        "version": "1",
        "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.123Z"
    },
    "event": {
        "id": "1234",
        "broadcaster_user_id": "1337",
        "broadcaster_user_login": "cool_user",
        "broadcaster_user_name": "Cool_User",
        "user_id": "9001",
        "user_login": "cooler_user",
        "user_name": "Cooler_User",
        "user_input": "pogchamp",
        "status": "fulfilled",  // Either fulfilled or cancelled
        "reward": {
            "id": "9001",
            "title": "title",
            "cost": 100,
            "prompt": "reward prompt"
        },
        "redeemed_at": "2020-07-15T17:16:03.17106713Z"
    }
}

channel.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.

Authorization

Must have channel:read:hype_train scope.

Channel Hype Train Begin Request Body

Name Type Required? Description
type string yes The subscription type name: channel.hype_train.begin.
version string yes The subscription type version: 1.
condition  condition  yes Subscription-specific parameters. Pass in the broadcaster user ID for the channel you want to hype train begin notifications for.
transport  transport  yes Transport-specific parameters.

Channel Hype Train Begin Webhook Example

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

Channel Hype Train Begin Notification Payload

Name Type Description
subscription  subscription  Subscription information.
event  event  Event information. Contains hype train information like the level, goal, top contributors, start time, and expiration time.

Channel Hype Train Notification Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.hype_train.begin",
        "version": "1",
        "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.123Z"
    },
    "event": {
        "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 },
            { "user_id": "456", "user_login": "kappa", "user_name": "Kappa", "type": "subscription", "total": 45 }
        ],
        "last_contribution": { "user_id": "123", "user_login": "pogchamp", "user_name": "PogChamp", "type": "bits", "total": 50 },
        "started_at": "2020-07-15T17:16:03.17106713Z",
        "expires_at": "2020-07-15T17:16:11.17106713Z"
    }
}

channel.hype_train.progress

The channel.hype_train.progress subscription type sends a notification when a hype train makes progress on the specified channel. When a hype train starts, one channel.hype_train.progress event will be sent for each contribution that caused the hype train to begin (in addition to the channel.hype_train.begin event). 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.

After a 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.

Authorization

Must have channel:read:hype_train scope.

Channel Hype Train Progress Request Body

Name Type Required? Description
type string yes The subscription type name: channel.hype_train.progress.
version string yes The subscription type version: 1.
condition  condition  yes Subscription-specific parameters. Pass in the broadcaster user ID for the channel you want to hype train progress notifications for.
transport  transport  yes Transport-specific parameters.

Channel Hype Train Progress Webhook Example

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

Channel Hype Train Progress Notification Payload

Name Type Description
subscription  subscription  Subscription information.
event  event  Event information. Contains hype train information like the level, goal, top contributors, last contribution, start time, and expiration time.

Channel Hype Train Progress Notification Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.hype_train.progress",
        "version": "1",
        "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.123Z"
    },
    "event": {
        "broadcaster_user_id": "1337",
        "broadcaster_user_login": "cool_user",
        "broadcaster_user_name": "Cool_User",
        "level": 2,
        "total": 700,
        "progress": 200,
        "goal": 1000,
        "top_contributions": [
            { "user_id": "123", "user_login": "pogchamp", "user_name": "PogChamp", "type": "bits", "total": 50 },
            { "user_id": "456", "user_login": "kappa", "user_name": "Kappa", "type": "subscription", "total": 45 }
        ],
        "last_contribution": { "user_id": "123", "user_login": "pogchamp", "user_name": "PogChamp", "type": "bits", "total": 50 },
        "started_at": "2020-07-15T17:16:03.17106713Z",
        "expires_at": "2020-07-15T17:16:11.17106713Z"
    }
}

channel.hype_train.end

The channel.hype_train.end subscription type sends a notification when a hype train ends on the specified channel.

Authorization

Must have channel:read:hype_train scope.

Channel Hype Train End Request Body

Name Type Required? Description
type string yes The subscription type name: channel.hype_train.end.
version string yes The subscription type version: 1.
condition  condition  yes Subscription-specific parameters. Pass in the broadcaster user ID for the channel you want to hype train end notifications for.
transport  transport  yes Transport-specific parameters.

Channel Hype Train End Webhook Example

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

Channel Hype Train End Notification Payload

Name Type Description
subscription  subscription  Subscription information.
event  event  Event information. Contains hype train information like the level, top contributors, start time, end time, and cooldown end time.

Channel Hype Train End Notification Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.hype_train.end",
        "version": "1",
        "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.123Z"
    },
    "event": {
        "broadcaster_user_id": "1337",
        "broadcaster_user_login": "cool_user",
        "broadcaster_user_name": "Cool_User",
        "level": 2,
        "total": 137,
        "top_contributions": [
            { "user_id": "123", "user_login": "pogchamp", "user_name": "PogChamp", "type": "bits", "total": 50 },
            { "user_id": "456", "user_login": "kappa", "user_name": "Kappa", "type": "subscription", "total": 45 }
        ],
        "started_at": "2020-07-15T17:16:03.17106713Z",
        "ended_at": "2020-07-15T17:16:11.17106713Z",
        "cooldown_ends_at": "2020-07-15T18:16:11.17106713Z"
    }
}

Stream Subscriptions

stream.online

The stream.online subscription type sends a notification when the specified broadcaster starts a stream.

Authorization

No authorization required.

Stream Online Request Body

Name Type Required? Description
type string yes The subscription type name: stream.online.
version string yes The subscription type version: 1.
condition  condition  yes Subscription-specific parameters. Pass in the broadcaster user ID for the channel you want to get updates for.
transport  transport  yes Transport-specific parameters.

Stream Online Webhook Example

{
    "type": "stream.online",
    "version": "1",
    "condition": {
        "broadcaster_user_id": "1337"
    },
    "transport": {
        "method": "webhook",
        "callback": "https://example.com/webhooks/callback",
        "secret": "s3cRe7"
    }
}

Stream Online Notification Payload

Name Type Description
subscription  subscription  Subscription information.
event  event  Event information. Contains the stream ID, broadcaster user ID, broadcaster user name, and the stream type.

Stream Online Notification Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "stream.online",
        "version": "1",
        "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.123Z"
    },
    "event": {
        "id": "9001",
        "broadcaster_user_id": "1337",
        "broadcaster_user_login": "cool_user",
        "broadcaster_user_name": "Cool_User",
        "type": "live",
        "started_at": "2020-10-11T10:11:12.123Z"
    }
}

stream.offline

The stream.offline subscription type sends a notification when the specified broadcaster stops a stream.

Authorization

No authorization required.

Stream Offline Request Body

Name Type Required? Description
type string yes The subscription type name: stream.offline.
version string yes The subscription type version: 1.
condition  condition  yes Subscription-specific parameters. Pass in the broadcaster user ID for the channel you want to get updates for.
transport  transport  yes Transport-specific parameters.

Stream Offline Webhook Example

{
    "type": "stream.offline",
    "version": "1",
    "condition": {
        "broadcaster_user_id": "1337"
    },
    "transport": {
        "method": "webhook",
        "callback": "https://example.com/webhooks/callback",
        "secret": "s3cRe7"
    }
}

Stream Offline Notification Payload

Name Type Description
subscription  subscription  Subscription information.
event  event  Event information. Contains the broadcaster user ID and broadcaster user name.

Stream Offline Notification Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "stream.offline",
        "version": "1",
        "status": "enabled",
        "cost": 0,
        "condition": {
            "broadcaster_user_id": "1337"
        },
        "created_at": "2019-11-16T10:11:12.123Z",
         "transport": {
            "method": "webhook",
            "callback": "https://example.com/webhooks/callback"
        }
    },
    "event": {
        "broadcaster_user_id": "1337",
        "broadcaster_user_login": "cool_user",
        "broadcaster_user_name": "Cool_User"
    }
}

User Subscriptions

user.authorization.revoke

The user.authorization.revoke subscription type sends a notification when a user’s authorization has been revoked for your client id. Use this webhook to meet government requirements for handling user data, such as GDPR, LGPD, or CCPA.

Authorization

Provided client_id must match the client id in the application access token.

User Authorization Revoke Request Body

Name Type Required? Description
type string yes The subscription type name: user.authorization.revoke.
version string yes The subscription type version: 1.
condition  condition  yes Subscription-specific parameters. Pass in the client ID of the application you want to get user authorization revoke notifications for.
transport  transport  yes Transport-specific parameters.

User Authorization Revoke Webhook Example

{
    "type": "user.authorization.revoke",
    "version": "1",
    "condition": {
        "client_id": "1337"
    },
    "transport": {
        "method": "webhook",
        "callback": "https://example.com/webhooks/callback",
        "secret": "s3cRe7"
    }
}

User Authorization Revoke Notification Payload

Name Type Description
subscription  subscription  Subscription information.
event  event  Event information. Contains your application’s client ID and the user ID of the user who revoked authorization for your application.

User Authorization Revoke Notification Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "user.authorization.revoke",
        "version": "1",
        "status": "enabled",
        "cost": 0,
        "condition": {
            "client_id": "crq72vsaoijkc83xx42hz6i37"
        },
         "transport": {
            "method": "webhook",
            "callback": "https://example.com/webhooks/callback"
        },
        "created_at": "2019-11-16T10:11:12.123Z"
    },
    "event": {
        "client_id": "crq72vsaoijkc83xx42hz6i37",
        "user_id": "1337",
        "user_login": "cool_user",  // Null if the user no longer exists
        "user_name": "Cool_User"    // Null if the user no longer exists
    }
}

user.update

The user.update subscription type sends a notification when user updates their account.

Authorization

No authorization required. If you have the user:read:email scope, the notification will include email field.

User Update Request Body

Name Type Required? Description
type string yes The subscription type name: user.update.
version string yes The subscription type version: 1.
condition  condition  yes Subscription-specific parameters. Pass in the user ID for the user you want update notifications for.
transport  transport  yes Transport-specific parameters.

User Update Webhook Example

{
    "type": "user.update",
    "version": "1",
    "condition": {
        "user_id": "1337"
    },
    "transport": {
        "method": "webhook",
        "callback": "https://example.com/webhooks/callback",
        "secret": "s3cRe7"
    }
}

User Update Notification Payload

Name Type Description
subscription  subscription  Subscription information.
event  event  Event information. Contains the user ID, user name, and description. The user’s email is included if you have the user:read:emailscope for the user.

User Update Notification Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "user.update",
        "version": "1",
        "status": "enabled",
        "cost": 0,
        "condition": {
           "user_id": "1337"
        },
         "transport": {
            "method": "webhook",
            "callback": "https://example.com/webhooks/callback"
        },
        "created_at": "2019-11-16T10:11:12.123Z"
    },
    "event": {
        "user_id": "1337",
        "user_login": "cool_user",
        "user_name": "Cool_User",
        "email": "user@email.com",  // Requires user:read:email scope
        "description": "cool description"
    }
}