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

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.
When webhooks are not feasible, backend applications can utilize conduits backed by websockets.

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 outstanding 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).

tip

For webhooks and conduits, you can utilize user.authorization.revoke to track when users revoke authorization, so you can delete their EventSub subscriptions to avoid exceeding the max_total_cost.

When the max_total_cost is reached, new EventSub subscriptions cannot be created, even if they have zero cost.

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