Back View all Articles

Twitch Notifications (Part One): How to Handle Real-Time Events from Twitch

Posted by Aydrian Howard on January 21st, 2021

Over the last few years, Twitch has become the streaming platform for gaming, esports, live coding, DJ-ing, and more. If you’re a streamer, whether for work or for fun, you know that one of the biggest challenges is building your audience and attracting viewers to your Twitch channel when you go live. 

Unfortunately, the options for sending notifications in Twitch are pretty limited. When you go live, Twitch will automatically send your followers an email, push, or in-app notification. But this isn’t very helpful for acquiring new viewers or engaging your community outside of Twitch. 

In this series, I'll show you how to use Twitch EventSub and Courier to automatically send notifications to many destinations – Discord, Slack, Facebook Messenger, and more – when your stream begins. 

Have questions about sending notifications using Twitch EventSub and Courier? Join our new community on Discord – we're happy to help!

How to handle real-time events from Twitch

During last year's Twitch Developer Day, Twitch introduced EventSub as a single product to handle real-time events. EventSub is a transport-neutral solution that will eventually replace their existing PubSub and Webhook APIs. Today, EventSub only supports webhooks. 

Let's start by creating a Node.js application and use Express to expose a POST route that Twitch EventSub can communicate with.

Prerequisites

To complete this tutorial, you'll need a couple things:

  1. A Node.js v14.x dev environment

  2. The Twitch CLI (for testing)

We'll be creating a Node.js application that needs to be accessible externally. If you are working locally, you can use ngrok to expose your local endpoint. Alternatively, you can use a tool like Glitch to build and host your application.

Creating a basic Express Application

We'll start by creating an Express application with minimal features. First, create a new folder and initialize it with a package.json file.

Create a new Node.js application

Now we are able to install the Express package.

Install Express.js

Let's use express to create a simple HTTP server. Create an index.js file and add the following:

Create a simple HTTP server

Let's run our application by executing `node index.js` in the terminal. If you open http://localhost:3000 in your browser, you should see "Hello World!" 

Congrats! You now have a working (albeit minimal) Express server. Next, we'll add the ability to receive a POST request from Twitch.

Handling the Twitch POST request

In order to accept real-time events from Twitch, we'll need to create a callback URL. We can do this by creating a new POST route. In the index.js file above where the listener is created, add the following lines of code:

Create a new POST route

First, we are telling our Express application to use the express.json() middleware to parse any incoming JSON payloads. Then, we added a callback route that will log the request and return a 200 status. Twitch expects this 2XX response to confirm you've received the request. If it doesn't receive a response in a couple seconds, it will retry the request. 

Let's test this route using the Twitch CLI. Restart your application and use the following command to trigger a test subscribe event.

Test the POST Route using the Twitch CLI

In the terminal running your application, you should see the event JSON for a channel.subscribe event. Next, we'll want to handle callback verification.

Handling callback verification

When you subscribe to an event, EventSub will send an initial request to the callback URL you specified. It expects a `challenge` response to verify you own the callback URL. We can handle this by checking the value of the `Twitch-Eventsub-Message-Type` header and respond with the `challenge` value provided in the request payload.

Update the callback code to the following:

Handling callback verification

Let's test this using the Twitch CLI. Restart your application and run the following CLI command:

Testing subscription verification using the Twitch CLI

This command will send a fake "subscription" EventSub subscription and validate if the endpoint responded with a valid status code and response.

Verifying the request

When accepting webhooks, it's good practice to verify that it came from the expected sender. We can do this by using the signature provided in the `Twitch-Eventsub-Message-Signature` header. We can create our own signature using the message ID, timestamp, and secret provided when subscribing to the event and compare it to the signature provided.

Let's update our use of the express.json() middleware to include a verify function. Add the following lines to the top of your index.js file:

Verifying the request: Adding the crypto library and signing secret environment variable

And replace the `app.use(express.json());` line with the following lines of code:

Verifying the request: Updating the json middleware to use a verify function

We just added a function to handle verifying the signature using the information from the request headers and used the crypto library to generate our own signature to which to compare it. This process used the signing secret that I'm storing in an environment variable because, well, your signing secret should stay secret.

Let's test that the signature validation is working using the Twitch CLI. You'll want to restart your app with the following command that includes the environment variable. 

Starting the Express.js application with the signing secret environment variable

Then in another terminal, run the following CLI command:

Testing request verification using the Twitch CLI

You should now see the provided and computed signatures and that verification was successful.

Putting it all together: Full application code

Your finished application code should look like the following:

Full Node.js and Express.js Application Code

We now have a Node.js and Express application that can receive real-time events from Twitch using EventSub. We've tested it locally using the Twitch CLI but, remember, before you can start using it with Twitch, you'll need to make sure the route uses HTTPS and port 443 and is publicly available. If you want to continue running it locally, look into using ngrok.

So, what’s next?

In the next post, we'll walk through creating a subscription for the stream.online event and use Courier to design and send our notifications. In the meantime, feel free to create subscriptions to any of the many supported events and try out your application.

-Aydrian

Author
Aydrian Howard

Courier
GitHubtwitterLinkedInFacebookInstagram