HelixWebHooksApi

The API methods that deal with WebHooks.

Overview

Can be accessed using client.helix.webHooks on an ApiClient instance.

Before using these methods...

All of the methods in this class assume that you are already running a working WebHook listener at the given callback URL.

If you don't already have one, we recommend use of the twitch-webhooks library, which handles subscribing and unsubscribing to these topics automatically.

Example

const api = new ApiClient(new StaticAuthProvider(clientId, accessToken));
await api.helix.webHooks.subscribeToUserFollowsTo('125328655', { callbackUrl: 'https://example.com' });

Methods

getSubscriptions()

async

Retrieves the current WebHook subscriptions for the current client.

Requires an app access token to work; does not work with user tokens.

Return type: HelixPaginatedRequestWithTotal<HelixWebHookSubscriptionData, HelixWebHookSubscription>

sendHubRequest(options)

async

Sends an arbitrary request to subscribe to or unsubscribe from an event.

Parameter	Type	Description
options	HelixWebHookHubRequest	see below
options.callbackUrl	string	The URL to send notifications to.
options.mode	HubMode Whether to subscribe or unsubscribe from notifications. Aliased type: "subscribe" \| "unsubscribe"	Whether to subscribe or unsubscribe from notifications.
options.scope	string	The OAuth scope necessary to subscribe to or unsubscribe from the given topic.
options.secret	string	The secret to sign the notification payloads with.
options.topicUrl	string	What topic URL to subscribe to or unsubscribe from.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void

subscribeToBanEvents(broadcaster, options)

async

Subscribes to events representing a ban or unban.

Parameter	Type	Description
broadcaster	UserIdResolvable	The broadcaster for which to get notifications about bans or unbans in their channel.
options	HelixWebHookHubRequestOptions
options.callbackUrl	string	The URL to send notifications to.
options.secret	string	The secret to sign the notification payloads with.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void

subscribeToBanEventsForUser(broadcaster, user, options)

async

Subscribes to events representing a ban or unban.

Parameter	Type	Description
broadcaster	UserIdResolvable	The broadcaster for which to get notifications about bans or unbans in their channel.
user	UserIdResolvable	The user that is being banned or unbanned.
options	HelixWebHookHubRequestOptions
options.callbackUrl	string	The URL to send notifications to.
options.secret	string	The secret to sign the notification payloads with.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void

subscribeToExtensionTransactions(extensionId, options)

async

Subscribes to extension transactions.

Parameter	Type	Description
extensionId	string	The extension ID for which to get notifications about transactions.
options	HelixWebHookHubRequestOptions
options.callbackUrl	string	The URL to send notifications to.
options.secret	string	The secret to sign the notification payloads with.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void

subscribeToHypeTrainEvents(broadcasterId, options)

async

Subscribes to events representing a Hype Train progressing.

Parameter	Type	Description
broadcasterId	UserIdResolvable	The broadcaster / channel for which to get notifications about Hype Train events.
options	HelixWebHookHubRequestOptions
options.callbackUrl	string	The URL to send notifications to.
options.secret	string	The secret to sign the notification payloads with.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void

subscribeToModeratorEvents(broadcaster, options)

async

Subscribes to events representing a user gaining or losing moderator privileges in a channel.

Parameter	Type	Description
broadcaster	UserIdResolvable	The broadcaster for which to get notifications about moderator changes in their channel.
options	HelixWebHookHubRequestOptions
options.callbackUrl	string	The URL to send notifications to.
options.secret	string	The secret to sign the notification payloads with.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void

subscribeToModeratorEventsForUser(broadcaster, user, options)

async

Subscribes to events representing a user gaining or losing moderator privileges in a channel.

Parameter	Type	Description
broadcaster	UserIdResolvable	The broadcaster for which to get notifications about moderator changes in their channel.
user	UserIdResolvable	The user that is being modded or unmodded.
options	HelixWebHookHubRequestOptions
options.callbackUrl	string	The URL to send notifications to.
options.secret	string	The secret to sign the notification payloads with.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void

subscribeToStreamChanges(user, options)

async

Subscribes to events representing a stream changing, i.e. going live, offline or changing its title or category.

Parameter	Type	Description
user	UserIdResolvable	The user for which to get notifications about their streams changing.
options	HelixWebHookHubRequestOptions
options.callbackUrl	string	The URL to send notifications to.
options.secret	string	The secret to sign the notification payloads with.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void

subscribeToSubscriptionEvents(user, options)

async

Subscribes to events representing the start or end of a channel subscription.

Parameter	Type	Description
user	UserIdResolvable	The user for which to get notifications about subscriptions to their channel.
options	HelixWebHookHubRequestOptions
options.callbackUrl	string	The URL to send notifications to.
options.secret	string	The secret to sign the notification payloads with.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void

subscribeToUserChanges(user, options, withEmail)

async

Subscribes to events representing a user changing a public setting or their email address.

Parameter	Type	Description
user	UserIdResolvable	The user for which to get notifications about changing a setting.
options	HelixWebHookHubRequestOptions	see below
options.callbackUrl	string	The URL to send notifications to.
options.secret	string	The secret to sign the notification payloads with.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).
withEmail	boolean	Whether to subscribe to email address changes. This adds the necessary scope to read the email address to the request.

Return type: void

subscribeToUserFollowsFrom(user, options)

async

Subscribes to events representing a user following other users.

Parameter	Type	Description
user	UserIdResolvable	The user for which to get notifications about the users they will follow.
options	HelixWebHookHubRequestOptions
options.callbackUrl	string	The URL to send notifications to.
options.secret	string	The secret to sign the notification payloads with.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void

subscribeToUserFollowsTo(user, options)

async

Subscribes to events representing a user being followed by other users.

Parameter	Type	Description
user	UserIdResolvable	The user for which to get notifications about the users they will be followed by.
options	HelixWebHookHubRequestOptions
options.callbackUrl	string	The URL to send notifications to.
options.secret	string	The secret to sign the notification payloads with.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void

unsubscribeFromBanEvents(broadcaster, options)

async

Unsubscribes from events representing a ban or unban.

Parameter	Type	Description
broadcaster	UserIdResolvable	The broadcaster for which not to get any more notifications about bans or unbans in their channel.
options	HelixWebHookHubRequestOptions
options.callbackUrl	string	The URL to send notifications to.
options.secret	string	The secret to sign the notification payloads with.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void

unsubscribeFromBanEventsForUser(broadcaster, user, options)

async

Unsubscribes from events representing a ban or unban.

Parameter	Type	Description
broadcaster	UserIdResolvable	The broadcaster for which not to get any more notifications about bans or unbans in their channel.
user	UserIdResolvable	The user that is being banned or unbanned.
options	HelixWebHookHubRequestOptions
options.callbackUrl	string	The URL to send notifications to.
options.secret	string	The secret to sign the notification payloads with.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void

unsubscribeFromExtensionTransactions(extensionId, options)

async

Unsubscribes from extension transactions.

Parameter	Type	Description
extensionId	string	The extension ID for which not to get any more notifications about transactions.
options	HelixWebHookHubRequestOptions
options.callbackUrl	string	The URL to send notifications to.
options.secret	string	The secret to sign the notification payloads with.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void

unsubscribeFromHypeTrainEvents(broadcasterId, options)

async

Unsubscribes from events representing a Hype Train progressing.

Parameter	Type	Description
broadcasterId	UserIdResolvable	The broadcaster / channel for which to get notifications about Hype Train events.
options	HelixWebHookHubRequestOptions
options.callbackUrl	string	The URL to send notifications to.
options.secret	string	The secret to sign the notification payloads with.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void

unsubscribeFromModeratorEvents(broadcaster, options)

async

Unsubscribes from events representing a user gaining or losing moderator privileges in a channel.

Parameter	Type	Description
broadcaster	UserIdResolvable	The broadcaster for which not to get any more notifications about moderator changes in their channel.
options	HelixWebHookHubRequestOptions
options.callbackUrl	string	The URL to send notifications to.
options.secret	string	The secret to sign the notification payloads with.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void

unsubscribeFromModeratorEventsForUser(broadcaster, user, options)

async

Unsubscribes from events representing a user gaining or losing moderator privileges in a channel.

Parameter	Type	Description
broadcaster	UserIdResolvable	The broadcaster for which not to get any more notifications about moderator changes in their channel.
user	UserIdResolvable	The user that is being modded or unmodded.
options	HelixWebHookHubRequestOptions
options.callbackUrl	string	The URL to send notifications to.
options.secret	string	The secret to sign the notification payloads with.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void

unsubscribeFromStreamChanges(user, options)

async

Unsubscribes from events representing a stream changing.

Parameter	Type	Description
user	UserIdResolvable	The user for which not to get any more notifications about their streams changing.
options	HelixWebHookHubRequestOptions
options.callbackUrl	string	The URL to send notifications to.
options.secret	string	The secret to sign the notification payloads with.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void

unsubscribeFromSubscriptionEvents(user, options)

async

Unsubscribes from events representing the start or end of a channel subscription.

Parameter	Type	Description
user	UserIdResolvable	The user for which not to get any more notifications about subscriptions and unsubscriptions to their channel.
options	HelixWebHookHubRequestOptions
options.callbackUrl	string	The URL to send notifications to.
options.secret	string	The secret to sign the notification payloads with.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void

unsubscribeFromUserChanges(user, options)

async

Unsubscribes from events representing a user changing a public setting or their email address.

Parameter	Type	Description
user	UserIdResolvable	The user for which not to get any more notifications about changing a setting.
options	HelixWebHookHubRequestOptions
options.callbackUrl	string	The URL to send notifications to.
options.secret	string	The secret to sign the notification payloads with.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void

unsubscribeFromUserFollowsFrom(user, options)

async

Unsubscribes from events representing a user following other users.

Parameter	Type	Description
user	UserIdResolvable	The user for which to not get any more notifications about the users they will follow.
options	HelixWebHookHubRequestOptions
options.callbackUrl	string	The URL to send notifications to.
options.secret	string	The secret to sign the notification payloads with.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void

unsubscribeFromUserFollowsTo(user, options)

async

Unsubscribes from events representing a user being followed by other users.

Parameter	Type	Description
user	UserIdResolvable	The user for which to not get any more notifications about the users they will be followed by.
options	HelixWebHookHubRequestOptions
options.callbackUrl	string	The URL to send notifications to.
options.secret	string	The secret to sign the notification payloads with.
options.validityInSeconds	number	The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void

Basic usage

Upgrading

Classes

Interfaces

Enums

HelixWebHooksApi

Overview

Methods

Before using these methods...

Example

Methods

getSubscriptions()

sendHubRequest(options)

subscribeToBanEvents(broadcaster, options)

subscribeToBanEventsForUser(broadcaster, user, options)

subscribeToExtensionTransactions(extensionId, options)

subscribeToHypeTrainEvents(broadcasterId, options)

subscribeToModeratorEvents(broadcaster, options)

subscribeToModeratorEventsForUser(broadcaster, user, options)

subscribeToStreamChanges(user, options)

subscribeToSubscriptionEvents(user, options)

subscribeToUserChanges(user, options, withEmail)

subscribeToUserFollowsFrom(user, options)

subscribeToUserFollowsTo(user, options)

unsubscribeFromBanEvents(broadcaster, options)

unsubscribeFromBanEventsForUser(broadcaster, user, options)

unsubscribeFromExtensionTransactions(extensionId, options)

unsubscribeFromHypeTrainEvents(broadcasterId, options)

unsubscribeFromModeratorEvents(broadcaster, options)

unsubscribeFromModeratorEventsForUser(broadcaster, user, options)

unsubscribeFromStreamChanges(user, options)

unsubscribeFromSubscriptionEvents(user, options)

unsubscribeFromUserChanges(user, options)

unsubscribeFromUserFollowsFrom(user, options)

unsubscribeFromUserFollowsTo(user, options)