Legacy PubSub to EventSub Migration Guide

Overview

The following guide provides information to migrate from the legacy PubSub system to EventSub. Legacy PubSub was deprecated in April 2024 and is scheduled to be fully decomissioned in April 2025. For more details about the deprecation and the shutdown timeline, refer to Legacy PubSub deprecation and shutdown timeline.

Connection Management

EventSub allows receiving messages using Webhooks or WebSockets. For the easiest migration, you can use EventSub’s WebSocket similarly to PubSub’s WebSocket connection.

For both connection types, there are some differences to take into consideration:

PING/PONG

When receiving EventSub messages using Webhooks, there is no persistent connection and therefore no need to handle PING/PONG equivalents.

EventSub WebSocket uses standard WebSocket Ping frames, and expects a client to respond with a standard WebSocket Pong frame. This should be handled by virtually all major WebSocket libraries, including all web browser implementations.

Some PubSub implementations used PING as a manner to see when they last heard from the server. EventSub’s WebSocket provides this feature using a Keepalive message, which is purely informational and does not expect a response from your client.

For more information, see Ping Message.

Handling Connection Failures

When receiving EventSub messages using Webhooks, there is no persistent connection and therefore no need to handle connection failures. However, failure to process multiple webhook notifications by your server will result in subscription revocation. For more information, see Processing an Event.

When receiving EventSub messages using WebSockets, sometimes a Reconnect message will be sent. This is equivalent to PubSub’s RECONNECT message. Similar to PubSub, EventSub will send a reconnect_url as part of the RECONNECT message. All previous subscriptions will be retained on successful reconnect. For more information on handling this process, see Reconnect Message.

Authorization Revoked

When a subscription or authorization is revoked, EventSub notifies you by sending a special message where the status is set with the relevant details, such as authorization_revoked for authorization being revoked. Other types of revocation include the user account being deleted (user_removed), and the subscription type’s version being removed (version_removed).

Webhooks receiving this message will have a special HTTP header type to indicate the message type is revocation. For more information on handling this, see Revoking Your Subscription.

WebSocket connections receiving this message will have a different message_type defined in the metadata of the WebSocket message. The payload of the message will be similar to the JSON payload for Webhooks receiving the same type of message. For more information on handling this, see Revocation Message.

Subscription Management

While PubSub expects you to send topic subscription messages directly into the WebSocket connection using LISTEN, EventSub handles this by using the Twitch API.

To receive EventSub notifications, you will need to use the Create EventSub Subscription API. Each API call will only subscribe to a single EventSub event, so you will need to make multiple API calls to subscribe to multiple events.

For more information, see Managing Event Subscriptions.

Note: When using WebSockets to receive EventSub messages, you should not send any messages from your client to the WebSocket server. Doing so will cause the server to disconnect your WebSocket connection.

Rate Limits

EventSub offers a high subscription limit per connection, but still imposes a maximum limit depending on the connection type. To verify if the limit changes will affect your use case, refer to EventSub Subscription Limits.

Topic Equivalence

Each PubSub topic and its equivalent EventSub subscription type is listed in the following table to help update your application during the migration period.

PubSub Topic	EventSub Topic	Note
`channel-bits-events-v1.<channel_id>` `channel-bits-events-v2.<channel_id>`	Channel Cheer Channel Chat Message
`channel-bits-badge-unlocks.<channel_id>`	Channel Chat Notification	Exposed in the `bits_badge_tier` field.
`channel-points-channel-v1.<channel_id>`	Channel Points Custom Reward Redemption Add Channel Points Automatic Reward Redemption Add	“Automatic” rewards, which are rewards added to the channel automatically by Twitch (e.g. Highlight My Message), are split from rewards added by the user or via the Twitch API.
`channel-subscribe-events-v1.<channel_id>`	Channel Chat Notification Channel Subscribe** Channel Subscription End Channel Subscription Gift Channel Subscription Message	As with PubSub, resubscribes, which is a non-gift subscription occurring after the first month, are only sent when a user manually chooses to send it in chat. ** Channel Subscribe does not differentiate Prime and Tier 1 subscriptions, but uses the same scope as the PubSub topic.
`automod-queue.<moderator_id>.<channel_id>`	Automod Message Hold Channel Chat User Message Hold	Automod Message Hold is for use by broadcasters and moderators to see all held messages in chat. Channel Chat User Message Hold is for use by chatting users to know when their own messages are held.
`chat_moderator_actions.<user_id>.<channel_id>`	Channel Moderate	This topic handled a broad amount of moderator actions, and the direct replacement is Channel Moderate. There are other EventSub topics that are aligned with specific moderation actions (e.g. Channel Ban for chat bans).
`low-trust-users.<channel_id>.<suspicious_user_id>`	Channel Suspicious User Update Channel Suspicious User Message	This PubSub topic was split into multiple EventSub topics. “Low trust status” updates are now handled by Channel Suspicious User Update. New messages sent in chat by a potential ban evader are now handled by Channel Suspicious User Message.
`user-moderation-notifications.<current_user_id>.<channel_id>`	Automod Message Update Automod Message Update v2
`whispers.<user_id>`	Whisper Received

Authentication Scopes

Many of the EventSub equivalents for PubSub topics have different scope requirements. We have provided the following list to describe what the scope requirements are for the recommended EventSub subscriptions.

PubSub Topic	PubSub Scope	EventSub Scope	Note
`channel-bits-events-v1.<channel_id>` `channel-bits-events-v2.<channel_id>`	`bits:read`	Channel Cheer `bits:read` Channel Chat Message `user:read:chat` and applicable bot scopes	“Applicable bot scopes” are `user:bot`, and either `channel:bot` or moderator status in the broadcaster’s channel.
`channel-bits-badge-unlocks.<channel_id>`	`bits:read`	`user:read:chat` and applicable bot scopes.	“Applicable bot scopes” are `user:bot`, and either `channel:bot` or moderator status in the broadcaster’s channel.
`channel-points-channel-v1.<channel_id>`	`channel:read:redemptions`	`channel:read:redemptions` OR `channel:manage:redemptions`	All recommended EventSub events for this PubSub topic have identical scope requirements.
`channel-subscribe-events-v1.<channel_id>`	`channel:read:subscriptions`	Channel Chat Notification `user:read:chat` and applicable bot scopes. Channel Subscribe Channel Subscription End Channel Subscription Gift Channel Subscription Message `channel:read:subscriptions`	“Applicable bot scopes” are `user:bot`, and either `channel:bot` or moderator status in the broadcaster’s channel. All subscription-related events have identical scope requirements.
`automod-queue.<moderator_id>.<channel_id>`	`channel:moderate`	`moderator:manage:automod`	All recommended EventSub events for this PubSub topic have identical scope requirements.
`chat_moderator_actions.<user_id>.<channel_id>`	`channel:moderate`	`moderator:read:blocked_terms` OR `moderator:manage:blocked_terms` `moderator:read:chat_settings` OR `moderator:manage:chat_settings` `moderator:read:unban_requests` OR `moderator:manage:unban_requests` `moderator:read:banned_users` OR `moderator:manage:banned_users` `moderator:read:chat_messages` OR `moderator:manage:chat_messages` `moderator:read:moderators` `moderator:read:vips`	All listed EventSub scopes are required to subscribe to the event.
`low-trust-users.<channel_id>.<suspicious_user_id>`	`channel:moderate`	`moderator:read:suspicious_users`	All recommended EventSub events for this PubSub topic have identical scope requirements.
`user-moderation-notifications.<current_user_id>.<channel_id>`	`chat:read`	`moderator:manage:automod`	All recommended EventSub events for this PubSub topic have identical scope requirements.
`whispers.<user_id>`	`whispers:read`	`user:read:whispers` OR `user:manage:whispers`

Will this deprecation affect Extension PubSub?

No. Broadcasting messages for Extensions as documented on Building Extensions will not be affected by the broader PubSub deprecation and shutdown.