Twitch WebHook Mirror

A simple web service that forwards Twitch's EventSub events to a websocket.

Why

In the beginning, there was PubSub, a webhook-based method to get notifications from twitch. This is great for people like Streamlabs who run big ol' servers to handle a lot of traffic for a lot of users, but is a pain in the ass for individuals that want to consume these in a self-hosted, freedom respecting manner (as webhooks mean you need to run a server and make it public to the internet so twitch can connect push data whenever - a pain, but doable). Twitch also offers a very handy IRC server, but limits that to chat messages, cheers, and raids (notably, this is missing follow events, which are important for those just starting out).

In their infinite wisdom, twitch saw this was a pain point and added a new system called EventSub, which unlike PubSub that came before it is transport agnostic! No longer will we be shackled to-

wait, no, although they claim the new system is transport agnostic, they only implemented one transport: webhooks.

and they require TLS for webhooks, so you need to also register a domain and reverse proxies and all that fun stuff.

...and they dropped a lot of events, like follows, from PubSub.......

what do!?!?!????!?!

There are two choices: suck it up and pay for a server to get those precious webhook-only events, or suck it up and wait for twitch to add a websocket-or-similar transport for EventSub.

This program is made to facilitate the first, and since not everyone has the technical knowledge nor funds to do such a thing, enables one server to be setup by a kind soul and used by many.

Usage

1. Connect one or more websockets to /ws/[your_unique_id]

2. Use the Twitch API to make an EventSub subscription with the callback url /webhook/[your_unique_id]

3. For every event sent to the webhook, you'll receive JSON containing three fields: an autogenerated id (not the same as the event id!), the EventSub event data, and all of the EventSub headers as headers.

   Of note: since this proxy never knows your secret, you must verify the integrity of the data yourself. See the EventSub docs.

   At this time, this proxy also does protect you from replay attacks - this may change in the future though.

Hosting

To host your own, you will need Redis, Python 3.9, pipenv, a reverse proxy (such as Nginx), and a domain to which you can get a TLS certificate.

1. Clone this repo

2. Install dependencies via pipenv sync

   Depending on your system, the wsaccel wheel may not work for you, in which case pipenv will compile it for you. For that, you will also need the Python 3.9 header files (python3-dev or python3-devel for linux folks) as well as gcc.

3. Adjust the REDIS_URL (and other properties) in config.toml as needed

4. Run pipenv run gunicorn -k flask_sockets.worker app:app as a non-superuser service (in linux, the way to do that is a systemd service)

5. Configure your reverse proxy with a TLS certificate (tools such as certbot highly recommended) to point back to this application, making sure to allow websockets (http -> ws upgrade procedure not needed - our library will do that if needed)

   If this seems a little "draw the rest of the owl", it sorta is. Here be the dragons that keeps this out of most peoples reach, this sorta thing isn't something that can be easily explained in a README.