EventSub is a transport-neutral real time notification delivery service. EventSub was launched in 2020 with support for notifications via Webhooks. Last month, we launched support for EventSub notifications via WebSockets. Today, we’re proposing a new transport type called a Conduit.
When we added WebSocket support to EventSub, we focused on supporting applications that run on end customer devices. We heard from backend application developers interested in receiving notifications over WebSockets on their backend servers.
Large backend applications often create and maintain millions of EventSub subscriptions across their user base. These applications need to load balance high throughput notifications across multiple server-side processes with resilience. Additionally, WebSocket subscriptions do not last beyond the lifetime of the connection. For backend applications with a large user base, short-lived subscriptions tied to the status of the WebSocket connection can result in sub-optimal user experiences when a connection is lost.
Conduit transport type is a wrapper that separates your subscriptions from the underlying transport and load balances notifications across shards. A shard is a Webhook or WebSocket connection and a Conduit is a collection of shards. The Conduit transport type is for backend server applications and requires app access tokens. We will be introducing new EventSub APIs to manage the Conduit lifecycle.
First, you create a conduit and specify the number of shards you need. If you want the conduit to deliver over WebSockets, you then create the desired number of WebSocket sessions. Then you associate your WebSocket sessions or Webhook callbacks with specific shards in the conduit. Here’s how that looks:
Associate your WebSocket session with a conduit within 10s of establishing the connection to avoid being disconnected.
You can add subscriptions to a conduit by specifying the conduit ID as the transport type when you create the subscription. EventSub routes notifications to your conduit shards. EventSub uses a hashing mechanism to determine the shard that notifications for a particular channel ID will be delivered on. Subscriptions are disabled when a conduit is deleted.
Subscriptions are associated with the new transport type via Conduit ID at creation.
Developers can scale up and scale down based on user behavior. Use the EventSub Update Conduit API to scale up or scale down by changing the number of shards available to the Conduit. Here’s the flow for scaling up:
You can scale down by reducing the shard count on a conduit. For example, updating the shard count from 100 to 50 will disable shards with ids 50-99.
EventSub can disable individual shards within a Conduit (e.g., after a websocket session disconnects). When a shard is disabled, we’ll send a notification via a new shard disabled subscription type. If your shard is disabled, you can create another session and update the conduit via API.
If all the shards associated with a Conduit are disabled, the Conduit will remain enabled. However, if no shard is reactivated after 72 hours (subject to change), EventSub will delete the Conduit. This allows developers to recover from full outages without needing to recreate every subscription associated with their system.
Creating a conduit and associating subscriptions with it requires an app access token.
We will limit clients to 5 enabled conduits with a maximum of 20,000 shards per conduit (all numbers provided are subject to change). Subscriptions associated with conduits will use the same cost model EventSub has today.
When will this be available?
We’re excited for beta participants in Q4 2023. Look for more details soon!
How long does a conduit persist?
Conduits persist while their associated shards are enabled.
Do subscriptions on conduits persist indefinitely?
No. if all shards are disabled for 72 hours (subject to change), EventSub will delete the conduit and revoke its subscriptions.
Can I specify the shard that EventSub should use to send notifications for a particular channel?
No. EventSub uses a consistent hashing algorithm to determine the shard. The number of shards associated with the conduit is an input into the hashing algorithm.
Can I create a Conduit with only one shard?
Yes, you can create a Conduit with one shard. Conduits will not have a minimum required shard count. We may in the future put in protections against hot shards.
Will notifications be distributed amongst the disabled shards? For example, If my shard count is 20,000 and I have 5 enabled shards will notifications be lost or will they be delivered on the enabled shards?
EventSub would likely drop notifications in this scenario. When EventSub sends a notification to a disabled shard, it retries once to send the notification on another shard. If the 2nd shard is also disabled, EventSub drops the notification. For best results, you should update your shard count as needed and avoid having disabled shards. We will create a new “shard disabled” subscription type so you’ll know when a shard is disabled and be able to react appropriately.