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:
  • 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
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: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:

None

Raises:
  • ValueError – if subscribe_least_seconds is not in range 300 to 864000
  • RuntimeError – if webhook is already running
stop()

Stops the Webhook

Please make sure to unsubscribe from all subscriptions!

Return type:None
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.