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

twitch (Twitch) – a authenticated instance of Twitch

Return type

None

Raises

RuntimeError – if the callback URL does not use HTTPS

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

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.

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.

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