EventSub

EventSub is a transport-agnostic solution to receive real-time events from Twitch.

Twitch4J implements all the EventSub subscription types and corresponding events.

note

Twitch plans to deprecate third-party PubSub in favor of EventSub. Similarly, IRC will face additional restrictions (e.g., concurrent join limits) in favor of chat over EventSub. Thus, you should try to use EventSub when possible.

Transports

EventSub supports the following transport types:

• Webhook
• WebSocket
• Conduits (upcoming)

tip

The library handles websockets for you, so this transport tends to be easier to use.
Webhooks, on the other hand, require more code on your end to establish an HTTPS webserver and keep the EventSub subscription healthy.

Subscription Basics

To receive EventSub events, you must create an EventSub subscription. Each subscription has a type, which identifies the type of event you wish to receive. Twitch list all of the public subscription types in their documentation.

Each subscription has a condition, which identifies the parameters under which the event fires. For example, most subscriptions are conditioned by the ID of the channel in which the event occurred.

Each subscription has a cost, which is determined by the type of authorization you have. By default, the cost of a subscription is 1, but is reduced to 0 if you have a user access token from the channel related to the subscription. Each transport mechanism imposes different limits on the total cost (i.e., max_total_cost) across your enabled subscriptions for that transport type.

To establish an EventSub subscription, you must obtain an instance of EventSubSubscription, which is passed to TwitchHelix#createEventSubSubscription. It is easiest to create EventSubSubscription instances through our SubscriptionTypes utility class: SubscriptionType#prepareSubscription creates a subscription for the specified condition and transport, which should be passed to IEventSubSocket#register (when using websocket) or TwitchHelix#createEventSubSubscription (when using webhook).

You can query your oustanding EventSub subscriptions via TwitchHelix#getEventSubSubscriptions. This endpoint supports filtering by the subscription type, subscription status (e.g., enabled or disabled), and user id (for subscriptions related to a specific channel).

To delete an EventSub subscription, simply call IEventSubSocket#unregister (when using websocket) or TwitchHelix#deleteEventSubSubscription (when using webhook).

For further clarification, please read through Twitch's official documentation on managing EventSub subscriptions.