twitchAPI.eventsub

Full Implementation of the Twitch EventSub

The EventSub client runs in its own thread, calling the given callback function whenever an event happens.

Look at the Twitch EventSub reference to find the topics you are interested in.

Requirements

You need to have a public IP with a port open. That port will be 80 by default. You need app authentication and your Endpoint URL must point to a

Note

Please note that Your Endpoint URL has to be HTTPS, has to run on Port 443 and requires a valid, non self signed certificate This most likely means, that you need a reverse proxy like nginx. You can also hand in a valid ssl context to be used in the constructor.

You can check on whether or not your webhook is publicly reachable by navigating to the URL set in callback_url. You should get a 200 response with the text pyTwitchAPI eventsub.

Listening to topics

After you started your EventSub client, you can use the listen_ prefixed functions to listen to the topics you are interested in.

The function you hand in as callback will be called whenever that event happens with the event data as a parameter.

Short code example:

from pprint import pprint
from twitchAPI import Twitch, EventSub

# this will be called whenever someone follows the target channel
async def on_follow(data: dict):
    pprint(data)

TARGET_USERNAME = 'target_username_here'
WEBHOOK_URL = 'https://url.to.your.webhook.com'
APP_ID = 'your_app_id'
APP_SECRET = 'your_app_secret'

twitch = Twitch(APP_ID, APP_SECRET)
twitch.authenticate_app([])

uid = twitch.get_users(logins=[TARGET_USERNAME])
user_id = uid['data'][0]['id']
# basic setup, will run on port 8080 and a reverse proxy takes care of the https and certificate
hook = EventSub(WEBHOOK_URL, APP_ID, 8080, twitch)
# unsubscribe from all to get a clean slate
hook.unsubscribe_all()
# start client
hook.start()
print('subscribing to hooks:')
hook.listen_channel_follow(user_id, on_follow)

try:
    input('press Enter to shut down...')
finally:
    hook.stop()
print('done')

Class Documentation:

class twitchAPI.eventsub.EventSub(callback_url: str, api_client_id: str, port: int, twitch: twitchAPI.twitch.Twitch, ssl_context: Optional[ssl.SSLContext] = None)

EventSub integration for the Twitch Helix API.

Parameters
  • callback_url (str) – The full URL of the webhook.

  • api_client_id (str) – The id of your API client

  • port (int) – the port on which this webhook should run

  • ssl_context (SSLContext) – optional ssl context to be used

    Default: None

  • twitch (Twitch) – a app authenticated instance of Twitch

Variables
  • secret (str) – A random secret string. Set this for added security.

  • callback_url (str) – The full URL of the webhook.

  • wait_for_subscription_confirm (bool) – Set this to false if you don’t want to wait for a subscription confirm.

    Default: True

  • wait_for_subscription_confirm_timeout (int) – Max time in seconds to wait for a subscription confirmation. Only used if wait_for_subscription_confirm is set to True.

    Default: 30

  • unsubscribe_on_stop (bool) – Unsubscribe all currently active Webhooks on calling stop()

    Default: True

start()

Starts the EventSub client

Return type

None

Raises

RuntimeError – if EventSub is already running

stop()

Stops the EventSub client

This also unsubscribes from all known subscriptions if unsubscribe_on_stop is True

Return type

None

unsubscribe_all()

Unsubscribe from all subscriptions

unsubscribe_all_known()

Unsubscribe from all subscriptions known to this client.

unsubscribe_topic(topic_id: str) bool

Unsubscribe from a specific topic.

listen_channel_update(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

A broadcaster updates their channel properties e.g., category, title, mature flag, broadcast, or language.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelupdate

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_follow(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

A specified channel receives a follow.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelfollow

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_subscribe(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

A notification when a specified channel receives a subscriber. This does not include resubscribes.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelsubscribe

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_subscription_end(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

A notification when a subscription to the specified channel ends.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelsubscriptionend

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_subscription_gift(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

A notification when a viewer gives a gift subscription to one or more users in the specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelsubscriptiongift

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_subscription_message(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

A notification when a user sends a resubscription chat message in a specific channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelsubscriptionmessage

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_cheer(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

A user cheers on the specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelcheer

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_raid(callback: Callable[[dict], Awaitable[None]], to_broadcaster_user_id: Optional[str] = None, from_broadcaster_user_id: Optional[str] = None) str

A broadcaster raids another broadcaster’s channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelraid

Parameters
  • from_broadcaster_user_id (str) – The broadcaster user ID that created the channel raid you want to get notifications for.

  • to_broadcaster_user_id (str) – The broadcaster user ID that received the channel raid you want to get notifications for.

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_ban(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

A viewer is banned from the specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelban

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_unban(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

A viewer is unbanned from the specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelunban

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_moderator_add(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

Moderator privileges were added to a user on a specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelmoderatoradd

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_moderator_remove(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

Moderator privileges were removed from a user on a specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelmoderatorremove

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_points_custom_reward_add(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

A custom channel points reward has been created for the specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelchannel_points_custom_rewardadd

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_points_custom_reward_update(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]], reward_id: Optional[str] = None) str

A custom channel points reward has been updated for the specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelchannel_points_custom_rewardupdate

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • reward_id (str) – the id of the reward you want to get updates from.

    Default: None

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_points_custom_reward_remove(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]], reward_id: Optional[str] = None) str

A custom channel points reward has been removed from the specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelchannel_points_custom_rewardremove

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • reward_id (str) – the id of the reward you want to get updates from.

    Default: None

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_points_custom_reward_redemption_add(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]], reward_id: Optional[str] = None) str

A viewer has redeemed a custom channel points reward on the specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelchannel_points_custom_reward_redemptionadd

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • reward_id (str) – the id of the reward you want to get updates from.

    Default: None

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_points_custom_reward_redemption_update(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]], reward_id: Optional[str] = None) str

A redemption of a channel points custom reward has been updated for the specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelchannel_points_custom_reward_redemptionupdate

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • reward_id (str) – the id of the reward you want to get updates from.

    Default: None

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_poll_begin(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

A poll started on a specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelpollbegin

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_poll_progress(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

Users respond to a poll on a specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelpollprogress

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_poll_end(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

A poll ended on a specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelpollend

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_prediction_begin(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

A Prediction started on a specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelpredictionbegin

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_prediction_progress(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

Users participated in a Prediction on a specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelpredictionprogress

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_prediction_lock(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

A Prediction was locked on a specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelpredictionlock

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_channel_prediction_end(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

A Prediction ended on a specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelpredictionend

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_drop_entitlement_grant(organisation_id: str, callback: Callable[[dict], Awaitable[None]], category_id: Optional[str] = None, campaign_id: Optional[str] = None) str

An entitlement for a Drop is granted to a user.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#dropentitlementgrant

Parameters
  • organisation_id (str) – The organization ID of the organization that owns the game on the developer portal.

  • category_id (str) – The category (or game) ID of the game for which entitlement notifications will be received.

    Default: None

  • campaign_id (str) – The campaign ID for a specific campaign for which entitlement notifications will be received.

    Default: None

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_extension_bits_transaction_create(extension_client_id: str, callback: Callable[[dict], Awaitable[None]]) str

A Bits transaction occurred for a specified Twitch Extension.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#extensionbits_transactioncreate

Parameters
  • extension_client_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_goal_begin(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

A goal begins on the specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelgoalbegin

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_goal_progress(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

A goal makes progress on the specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelgoalprogress

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_goal_end(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

A goal ends on the specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelgoalend

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_hype_train_begin(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

A Hype Train begins on the specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelhype_trainbegin

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_hype_train_progress(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

A Hype Train makes progress on the specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelhype_trainprogress

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_hype_train_end(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

A Hype Train ends on the specified channel.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelhype_trainend

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_stream_online(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

The specified broadcaster starts a stream.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#streamonline

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_stream_offline(broadcaster_user_id: str, callback: Callable[[dict], Awaitable[None]]) str

The specified broadcaster stops a stream.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#streamoffline

Parameters
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_user_authorization_grant(client_id: str, callback: Callable[[dict], Awaitable[None]]) str

A user’s authorization has been granted to your client id.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#userauthorizationgrant

Parameters
  • client_id (str) – Your application’s client id.

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_user_authorization_revoke(client_id: str, callback: Callable[[dict], Awaitable[None]]) str

A user’s authorization has been revoked for your client id.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#userauthorizationrevoke

Parameters
  • client_id (str) – Your application’s client id.

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str

listen_user_update(user_id: str, callback: Callable[[dict], Awaitable[None]]) str

A user has updated their account.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#userupdate

Parameters
  • user_id (str) – The user ID for the user you want update notifications for.

  • callback (Callable[[dict],Awaitable[None]]) – function for callback

Raises
Return type

str