twitcheasy-twitch-bottwitch-authtwitch-auth-tmitwitch-chat-clienttwitch-eventsubtwitch-pubsub-clienttwitch-webhooks
Welcome

Basic usage

Getting startedCreating a client instanceCalling the Twitch APIFAQ

Upgrading

Upgrading to 2.xUpgrading to 3.xUpgrading to 4.x

Classes

ApiClientBadgesApiBitsApiChannelChannelApiChannelFollowChannelPlaceholderChannelSubscriptionChatApiChatBadgeListChatBadgeSetChatBadgeVersionChatEmoteListChattersListCheermoteListConfigErrorCreatedVideoEmoteSetListHelixApiGroupHelixBanHelixBanEventHelixBitsApiHelixBitsLeaderboardHelixBitsLeaderboardEntryHelixChannelHelixChannelApiHelixChannelEditorHelixChannelPointsApiHelixChannelSearchResultHelixCheermoteListHelixClipHelixClipApiHelixCustomRewardHelixCustomRewardRedemptionHelixEventSubApiHelixEventSubSubscriptionHelixExtensionsApiHelixExtensionTransactionHelixFollowHelixGameHelixGameApiHelixHypeTrainApiHelixHypeTrainContributionHelixHypeTrainEventHelixInstalledExtensionHelixInstalledExtensionListHelixModerationApiHelixModeratorHelixModeratorEventHelixPaginatedRequestHelixPaginatedRequestWithTotalHelixPrivilegedUserHelixSearchApiHelixStreamHelixStreamApiHelixStreamMarkerHelixStreamMarkerWithVideoHelixSubscriptionHelixSubscriptionApiHelixSubscriptionEventHelixTagHelixTagApiHelixTeamHelixTeamApiHelixTeamWithUsersHelixUserHelixUserApiHelixUserBlockHelixUserExtensionHelixUserRelationHelixVideoHelixVideoApiHelixWebHooksApiHelixWebHookSubscriptionKrakenApiGroupNoSubscriptionProgramErrorPrivilegedChannelPrivilegedUserSearchApiStreamStreamApiStreamNotLiveErrorSubscriptionTeamTeamApiTeamWithUsersUnsupportedApiUserUserApiUserBlockUserChatInfoUserFollowUserSubscriptionVideoVideoApi

Interfaces

ApiConfigChannelUpdateDataHelixBanFilterHelixBitsLeaderboardQueryHelixChannelSearchFilterHelixChannelUpdateHelixClipCreateParamsHelixClipFilterHelixCreateCustomRewardDataHelixCustomRewardRedemptionFilterHelixEventSubWebHookTransportOptionsHelixExtensionTransactionsFilterHelixExtensionTransactionsPaginatedFilterHelixFollowFilterHelixForwardPaginationHelixModeratorFilterHelixPaginatedChannelSearchFilterHelixPaginatedCustomRewardRedemptionFilterHelixPaginatedResponseHelixPaginatedResponseWithTotalHelixPaginatedResultHelixPaginatedResultWithTotalHelixPaginatedStreamFilterHelixPaginatedVideoFilterHelixPaginationHelixStreamFilterHelixUpdateCustomRewardDataHelixUserBlockAdditionalInfoHelixUserExtensionUpdatePayloadHelixUserExtensionUpdatePayloadActiveSlotHelixUserExtensionUpdatePayloadInactiveSlotHelixUserUpdateHelixVideoFilterHelixWebHookHubRequestHelixWebHookHubRequestOptionsVideoCreateDataVideoUpdateData

Enums

HelixBanEventTypeHelixBroadcasterTypeHelixModeratorEventTypeHelixStreamTypeHelixSubscriptionEventTypeStreamType

HelixWebHooksApi

The API methods that deal with WebHooks.

Overview

Methods

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 Required Default Description
options HelixWebHookHubRequest none see below
options.callbackUrl string none

The URL to send notifications to.
options.mode
HubMode

Whether to subscribe or unsubscribe from notifications.

Aliased type: "subscribe" | "unsubscribe"

none

Whether to subscribe or unsubscribe from notifications.

options.scope string none

The OAuth scope necessary to subscribe to or unsubscribe from the given topic.

options.secret string none

The secret to sign the notification payloads with.

options.topicUrl string none

What topic URL to subscribe to or unsubscribe from.

options.validityInSeconds number none

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 Required Default Description
broadcaster UserIdResolvable none

The broadcaster for which to get notifications about bans or unbans in their channel.

options HelixWebHookHubRequestOptions none
options.callbackUrl string none

The URL to send notifications to.
options.secret string none

The secret to sign the notification payloads with.

options.validityInSeconds number none

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 Required Default Description
broadcaster UserIdResolvable none

The broadcaster for which to get notifications about bans or unbans in their channel.

user UserIdResolvable none

The user that is being banned or unbanned.
options HelixWebHookHubRequestOptions none
options.callbackUrl string none

The URL to send notifications to.
options.secret string none

The secret to sign the notification payloads with.

options.validityInSeconds number none

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 Required Default Description
extensionId string none

The extension ID for which to get notifications about transactions.

options HelixWebHookHubRequestOptions none
options.callbackUrl string none

The URL to send notifications to.
options.secret string none

The secret to sign the notification payloads with.

options.validityInSeconds number none

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 Required Default Description
broadcasterId UserIdResolvable none

The broadcaster / channel for which to get notifications about Hype Train events.

options HelixWebHookHubRequestOptions none
options.callbackUrl string none

The URL to send notifications to.
options.secret string none

The secret to sign the notification payloads with.

options.validityInSeconds number none

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 Required Default Description
broadcaster UserIdResolvable none

The broadcaster for which to get notifications about moderator changes in their channel.

options HelixWebHookHubRequestOptions none
options.callbackUrl string none

The URL to send notifications to.
options.secret string none

The secret to sign the notification payloads with.

options.validityInSeconds number none

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 Required Default Description
broadcaster UserIdResolvable none

The broadcaster for which to get notifications about moderator changes in their channel.

user UserIdResolvable none

The user that is being modded or unmodded.
options HelixWebHookHubRequestOptions none
options.callbackUrl string none

The URL to send notifications to.
options.secret string none

The secret to sign the notification payloads with.

options.validityInSeconds number none

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 Required Default Description
user UserIdResolvable none

The user for which to get notifications about their streams changing.

options HelixWebHookHubRequestOptions none
options.callbackUrl string none

The URL to send notifications to.
options.secret string none

The secret to sign the notification payloads with.

options.validityInSeconds number none

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 Required Default Description
user UserIdResolvable none

The user for which to get notifications about subscriptions to their channel.

options HelixWebHookHubRequestOptions none
options.callbackUrl string none

The URL to send notifications to.
options.secret string none

The secret to sign the notification payloads with.

options.validityInSeconds number none

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 Required Default Description
user UserIdResolvable none

The user for which to get notifications about changing a setting.

options HelixWebHookHubRequestOptions none see below
options.callbackUrl string none

The URL to send notifications to.
options.secret string none

The secret to sign the notification payloads with.

options.validityInSeconds number none

The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

withEmail boolean false

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 Required Default Description
user UserIdResolvable none

The user for which to get notifications about the users they will follow.

options HelixWebHookHubRequestOptions none
options.callbackUrl string none

The URL to send notifications to.
options.secret string none

The secret to sign the notification payloads with.

options.validityInSeconds number none

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 Required Default Description
user UserIdResolvable none

The user for which to get notifications about the users they will be followed by.

options HelixWebHookHubRequestOptions none
options.callbackUrl string none

The URL to send notifications to.
options.secret string none

The secret to sign the notification payloads with.

options.validityInSeconds number none

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 Required Default Description
broadcaster UserIdResolvable none

The broadcaster for which not to get any more notifications about bans or unbans in their channel.

options HelixWebHookHubRequestOptions none
options.callbackUrl string none

The URL to send notifications to.
options.secret string none

The secret to sign the notification payloads with.

options.validityInSeconds number none

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 Required Default Description
broadcaster UserIdResolvable none

The broadcaster for which not to get any more notifications about bans or unbans in their channel.

user UserIdResolvable none

The user that is being banned or unbanned.
options HelixWebHookHubRequestOptions none
options.callbackUrl string none

The URL to send notifications to.
options.secret string none

The secret to sign the notification payloads with.

options.validityInSeconds number none

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 Required Default Description
extensionId string none

The extension ID for which not to get any more notifications about transactions.

options HelixWebHookHubRequestOptions none
options.callbackUrl string none

The URL to send notifications to.
options.secret string none

The secret to sign the notification payloads with.

options.validityInSeconds number none

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 Required Default Description
broadcasterId UserIdResolvable none

The broadcaster / channel for which to get notifications about Hype Train events.

options HelixWebHookHubRequestOptions none
options.callbackUrl string none

The URL to send notifications to.
options.secret string none

The secret to sign the notification payloads with.

options.validityInSeconds number none

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 Required Default Description
broadcaster UserIdResolvable none

The broadcaster for which not to get any more notifications about moderator changes in their channel.

options HelixWebHookHubRequestOptions none
options.callbackUrl string none

The URL to send notifications to.
options.secret string none

The secret to sign the notification payloads with.

options.validityInSeconds number none

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 Required Default Description
broadcaster UserIdResolvable none

The broadcaster for which not to get any more notifications about moderator changes in their channel.

user UserIdResolvable none

The user that is being modded or unmodded.
options HelixWebHookHubRequestOptions none
options.callbackUrl string none

The URL to send notifications to.
options.secret string none

The secret to sign the notification payloads with.

options.validityInSeconds number none

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 Required Default Description
user UserIdResolvable none

The user for which not to get any more notifications about their streams changing.

options HelixWebHookHubRequestOptions none
options.callbackUrl string none

The URL to send notifications to.
options.secret string none

The secret to sign the notification payloads with.

options.validityInSeconds number none

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 Required Default Description
user UserIdResolvable none

The user for which not to get any more notifications about subscriptions and unsubscriptions to their channel.

options HelixWebHookHubRequestOptions none
options.callbackUrl string none

The URL to send notifications to.
options.secret string none

The secret to sign the notification payloads with.

options.validityInSeconds number none

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 Required Default Description
user UserIdResolvable none

The user for which not to get any more notifications about changing a setting.

options HelixWebHookHubRequestOptions none
options.callbackUrl string none

The URL to send notifications to.
options.secret string none

The secret to sign the notification payloads with.

options.validityInSeconds number none

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 Required Default Description
user UserIdResolvable none

The user for which to not get any more notifications about the users they will follow.

options HelixWebHookHubRequestOptions none
options.callbackUrl string none

The URL to send notifications to.
options.secret string none

The secret to sign the notification payloads with.

options.validityInSeconds number none

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 Required Default Description
user UserIdResolvable none

The user for which to not get any more notifications about the users they will be followed by.

options HelixWebHookHubRequestOptions none
options.callbackUrl string none

The URL to send notifications to.
options.secret string none

The secret to sign the notification payloads with.

options.validityInSeconds number none

The number of seconds the subscription is valid for. Defaults to 3600 (1 hour). Can be at most 864000 (10 days).

Return type: void