twitchAPI.webhook¶
Full Implementation of the Twitch Webhook¶
Warning
Webhooks have been discontinued.
The Webhook runs in its own thread, calling the given callback function whenever an webhook event happens.
Look at the Twitch Webhook 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. Authentication is off by default but you can choose to authenticate to use some Webhook Topics or to get more information.
Note
Please note that Your Endpoint URL has to be HTTPS if you need authentication which means that you probably 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 webhook.
Short code example:¶
from twitchAPI.twitch import Twitch
from twitchAPI.webhook import TwitchWebHook
from pprint import pprint
def callback_stream_changed(uuid, data):
print('Callback for UUID ' + str(uuid))
pprint(data)
twitch = Twitch(td['app_id'], td['secret'])
twitch.authenticate_app([])
user_info = twitch.get_users(logins=['my_twitch_user'])
user_id = user_info['data'][0]['id']
# basic setup
# Please note that the first parameter is the domain your webhook is reachable from the outside, the last parameter
# is the port that the Webhook should use
hook = TwitchWebHook("https://my.cool.domain.net:443", 'my_app_id', 8080)
hook.authenticate(twitch)
hook.start()
print('subscribing to hook:')
success, uuid = hook.subscribe_stream_changed(user_id, callback_stream_changed)
pprint(success)
pprint(twitch.get_webhook_subscriptions())
# the webhook is now running and you are subscribed to the topic you want to listen to. lets idle a bit...
input('press Enter to shut down')
hook.stop()
print('done')
Subscription handling¶
You can subscribe to webhook topics using the subscribe_
prefixed methods.
If wait_for_subscription_confirm
is True (default), this will wait for the full handshake and
confirmation to happen, otherwise the returned success value might be inaccurate in case the subscription itself
succeeded but the final handshake failed.
You can unsubscribe from a webhook subscription at any time by using unsubscribe()
If unsubscribe_on_stop
is True (default), you don’t need to manually unsubscribe from topics.
By default, subscriptions will be automatically renewed one minute before they run out for as long as the webhook is running.
You can also use unsubscribe_all()
to unsubscribe from all topic subscriptions at
once. This will also unsubscribe from topics that where left over from a previous run.
Fixing typical problems¶
Make sure that your set URL is reachable from outside your network.
Make sure that you use a non self signed SSL certificate (use one from e.g. Let’s Encrypt) if you use any Authentication.
If you change your domain’s DNS, it can take up to 24 hours (or more) to propagate the changes across the entire internet and reach the Twitch servers.
Class Documentation:¶
- class twitchAPI.webhook.TwitchWebHook(callback_url: str, api_client_id: str, port: int, ssl_context: Optional[ssl.SSLContext] = None)¶
Webhook 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
- Variables
secret (str) – A random secret string. Set this for added security.
callback_url (str) – The full URL of the webhook.
subscribe_least_seconds (int) – The duration in seconds for how long you want to subscribe to webhhoks. Min 300 Seconds, Max 864000 Seconds.
Default:600
auto_renew_subscription (bool) – If True, automatically renew all webhooks once they get close to running out. Only disable this if you know what you are doing.
Default:True
wait_for_subscription_confirm (bool) – Set this to false if you dont 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
- authenticate(twitch: twitchAPI.twitch.Twitch) → None¶
Set authentication for the Webhook. Can be either a app or user token.
- Parameters
- Return type
- Raises
RuntimeError – if the callback URL does not use HTTPS
- start()¶
Starts the Webhook
- Return type
- Raises
ValueError – if subscribe_least_seconds is not in range 300 to 864000
RuntimeError – if webhook is already running
- unsubscribe_all(twitch: twitchAPI.twitch.Twitch) → bool¶
Unsubscribe from all Webhooks that use the callback URL set in callback_url
If `wait_for_subscription_confirm` is False, the response might be True even tho the unsubscribe action failed.
- renew_subscription(uuid: uuid.UUID) → bool¶
Renew existing topic subscription
- Parameters
uuid – UUID of the subscription to renew
- Return type
- Returns
True if renewal worked. Note that you still need to wait for the handshake to make sure its renewed.
- subscribe_user_follow(from_id: Optional[str], to_id: Optional[str], callback_func: Optional[Callable[[uuid.UUID, dict], None]]) → Tuple[bool, uuid.UUID]¶
Subscribe to user follow topic.
Set only from_id if you want to know if User with that id follows someone.
Set only to_id if you want to know if someone follows User with that id.
Set both if you only want to know if from_id follows to_id.
See https://dev.twitch.tv/docs/api/webhooks-reference#topic-user-follows for documentation
- Parameters
from_id – str or None
to_id – str or None
callback_func – function for callback
- Raises
ValueError – if both from_id and to_id are None
- Return type
bool, UUID
- subscribe_stream_changed(user_id: str, callback_func: Optional[Callable[[uuid.UUID, dict], None]]) → Tuple[bool, uuid.UUID]¶
Subscribe to stream changed topic
See https://dev.twitch.tv/docs/api/webhooks-reference#topic-stream-changed for documentation
- Parameters
user_id – str
callback_func – function for callback
- Return type
bool, UUID
- subscribe_user_changed(user_id: str, callback_func: Optional[Callable[[uuid.UUID, dict], None]]) → Tuple[bool, uuid.UUID]¶
Subscribe to subscription event topic
See https://dev.twitch.tv/docs/api/webhooks-reference#topic-user-changed for documentation
- Parameters
user_id – str
callback_func – function for callback
- Return type
bool, UUID
- subscribe_extension_transaction_created(extension_id: str, callback_func: Optional[Callable[[uuid.UUID, dict], None]]) → Tuple[bool, uuid.UUID]¶
Subscribe to Extension transaction topic
See https://dev.twitch.tv/docs/api/webhooks-reference#topic-extension-transaction-created for documentation
- Parameters
extension_id – str
callback_func – function for callback
- Return type
bool, UUID
- subscribe_moderator_change_events(broadcaster_id: str, user_id: Optional[str], callback_func: Callable[[uuid.UUID, dict], None]) → Tuple[bool, uuid.UUID]¶
Subscribe to Moderator Change Events topic
See https://dev.twitch.tv/docs/api/webhooks-reference#topic-moderator-change-events for documentation
- Parameters
broadcaster_id – str
user_id – str or None
callback_func – function for callback
- Return type
bool, UUID
- subscribe_channel_ban_change_events(broadcaster_id: str, user_id: Optional[str], callback_func: Callable[[uuid.UUID, dict], None]) → Tuple[bool, uuid.UUID]¶
Subscribe to Channel Ban Change Events
See https://dev.twitch.tv/docs/api/webhooks-reference#topic-channel-ban-change-events for documentation
- Parameters
broadcaster_id – str
user_id – str or None
callback_func – function for callback
- Return type
bool, UUID
- subscribe_subscription_events(broadcaster_id: str, callback_func: Callable[[uuid.UUID, dict], None], user_id: Optional[str] = None, gifter_id: Optional[str] = None, gifter_name: Optional[str] = None) → Tuple[bool, uuid.UUID]¶
Subscribe to Subscription Events Topic
See https://dev.twitch.tv/docs/api/webhooks-reference#topic-subscription-events for documentation
- Parameters
broadcaster_id – str
callback_func – function for callback
user_id – optional str
gifter_id – optional str
gifter_name – optional str
- Return type
bool, UUID
- subscribe_hype_train_events(broadcaster_id: str, callback_func: Callable[[uuid.UUID, dict], None]) → Tuple[bool, uuid.UUID]¶
Subscribe to Hype Train Events
See https://dev.twitch.tv/docs/api/webhooks-reference#topic-hype-train-event for documentation
- Parameters
broadcaster_id – str
callback_func – function for callback
- Return type
bool, UUID