twitchAPI.webhook¶
Full Implementation of the Twitch Webhook¶
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. This lib currently does not provide any way to add https on its own.
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
hook = TwitchWebHook("https://my.cool.domain.net:8080", '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...\n')
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 dont need to manually unsubscribe from topics.
By deafult, 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.
Class Documentation:¶
-
class
twitchAPI.webhook.
TwitchWebHook
(callback_url: str, api_client_id: str, port: int)¶ Webhook integration for the Twitch Helix API.
Parameters: Variables: -
authenticate
(twitch: twitchAPI.twitch.Twitch) → None¶ Set authentication for the Webhook. Can be either a app or user token.
Parameters: twitch (Twitch) – a authenticated instance of Twitch
Return type: None Raises: RuntimeError – if the callback URL does not use HTTPS
-
renew_subscription
(uuid: uuid.UUID) → bool¶ Renew existing topic subscription
Parameters: uuid – UUID of the subscription to renew Return type: bool Returns: True if renewal worked. Note that you still need to wait for the handshake to make sure its renewed.
-
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
-
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_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_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
-
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_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_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_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_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
Return type: bool, UUID
-
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.
Parameters: twitch (Twitch) – App authorized instance of Twitch
Return type: bool Returns: True if all webhooks could be unsubscribed, otherwise False.
-