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

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.

• Part one (this post): We’ll create a small Node.js and Express app to accept webhooks from Twitch EventSub.
• Part two: We’ll subscribe to the stream.online event and process the request using Courier. Then, we’ll use Courier to create and design our notifications.
• Part three: Finally, we'll create a list of subscribers and use Courier to notify the entire list across multiple destinations with one API call.

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:

• A Node.js v14.x dev environment
• 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.

1
mkdir eventsub-handler && eventsub-handler
2
npm init --yes

Now we are able to install the Express package.

1
npm install express

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

1
const express = require("express");
2
const app = express();
3
const port = process.env.PORT || 3000;
4

5
app.get("/", (req, res) => {
6
  res.send("Hello World!");
7
});
8

9
const listener = app.listen(port, () => {
10
  console.log("Your app is listening on port " + listener.address().port);
11
});

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:

1
app.use(express.json());
2

3
app.post("/webhooks/callback", async (req, res) => {
4
  const { type } = req.body.subscription;
5
  const { event } = req.body;
6

7
  console.log(
8
    `Receiving ${type} request for ${event.broadcaster_user_name}: `,
9
    event
10
  );
11

12
  res.status(200).end();
13
});

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.

1
twitch event trigger subscribe -F http://localhost:3000/webhooks/callback

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:

1
app.post("/webhooks/callback", async (req, res) => {
2
  const messageType = req.header("Twitch-Eventsub-Message-Type");
3
  if (messageType === "webhook_callback_verification") {
4
    console.log("Verifying Webhook");
5
    return res.status(200).send(req.body.challenge);
6
  }
7

8
  const { type } = req.body.subscription;
9
  const { event } = req.body;
10

11
  console.log(
12
    `Receiving ${type} request for ${event.broadcaster_user_name}: `,
13
    event
14
  );
15

16
  res.status(200).end();
17
});

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

1
twitch event verify-subscription subscribe -F http://localhost:3000/webhooks/callback

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:

1
const crypto = require("crypto");
2
const twitchSigningSecret = process.env.TWITCH_SIGNING_SECRET;

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

1
const verifyTwitchSignature = (req, res, buf, encoding) => {
2
  const messageId = req.header("Twitch-Eventsub-Message-Id");
3
  const timestamp = req.header("Twitch-Eventsub-Message-Timestamp");
4
  const messageSignature = req.header("Twitch-Eventsub-Message-Signature");
5
  const time = Math.floor(new Date().getTime() / 1000);
6
  console.log(`Message ${messageId} Signature: `, messageSignature);
7

8
  if (Math.abs(time - timestamp) > 600) {
9
    // needs to be < 10 minutes
10
    console.log(`Verification Failed: timestamp > 10 minutes. Message Id: ${messageId}.`);
11
    throw new Error("Ignore this request.");
12
  }
13

14
  if (!twitchSigningSecret) {
15
    console.log(`Twitch signing secret is empty.`);
16
    throw new Error("Twitch signing secret is empty.");
17
  }
18

19
  const computedSignature =
20
    "sha256=" +
21
    crypto
22
      .createHmac("sha256", twitchSigningSecret)
23
      .update(messageId + timestamp + buf)
24
      .digest("hex");
25
  console.log(`Message ${messageId} Computed Signature: `, computedSignature);
26

27
  if (messageSignature !== computedSignature) {
28
    throw new Error("Invalid signature.");
29
  } else {
30
    console.log("Verification successful");
31
  }
32
};
33

34
app.use(express.json({ verify: verifyTwitchSignature }));

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.

1
TWITCH_SIGNING_SECRET=purplemonkeydishwasher node index.js

Then in another terminal, run the following CLI command:

1
twitch event trigger subscribe -F http://localhost:3000/webhooks/callback -s purplemonkeydishwasher

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:

1
const express = require("express");
2
const crypto = require("crypto");
3
const app = express();
4
const port = process.env.PORT || 3000;
5
const twitchSigningSecret = process.env.TWITCH_SIGNING_SECRET;
6

7
app.get("/", (req, res) => {
8
  res.send("Hello World!");
9
});
10

11
const verifyTwitchSignature = (req, res, buf, encoding) => {
12
  const messageId = req.header("Twitch-Eventsub-Message-Id");
13
  const timestamp = req.header("Twitch-Eventsub-Message-Timestamp");
14
  const messageSignature = req.header("Twitch-Eventsub-Message-Signature");
15
  const time = Math.floor(new Date().getTime() / 1000);
16
  console.log(`Message ${messageId} Signature: `, messageSignature);
17

18
  if (Math.abs(time - timestamp) > 600) {
19
    // needs to be < 10 minutes
20
    console.log(
21
      `Verification Failed: timestamp > 10 minutes. Message Id: ${messageId}.`
22
    );
23
    throw new Error("Ignore this request.");
24
  }
25

26
  if (!twitchSigningSecret) {
27
    console.log(`Twitch signing secret is empty.`);
28
    throw new Error("Twitch signing secret is empty.");
29
  }
30

31
  const computedSignature =
32
    "sha256=" +
33
    crypto
34
      .createHmac("sha256", twitchSigningSecret)
35
      .update(messageId + timestamp + buf)
36
      .digest("hex");
37
  console.log(`Message ${messageId} Computed Signature: `, computedSignature);
38

39
  if (messageSignature !== computedSignature) {
40
    throw new Error("Invalid signature.");
41
  } else {
42
    console.log("Verification successful");
43
  }
44
};
45

46
app.use(express.json({ verify: verifyTwitchSignature }));
47

48
app.post("/webhooks/callback", async (req, res) => {
49
  const messageType = req.header("Twitch-Eventsub-Message-Type");
50
  if (messageType === "webhook_callback_verification") {
51
    console.log("Verifying Webhook");
52
    return res.status(200).send(req.body.challenge);
53
  }
54

55
  const { type } = req.body.subscription;
56
  const { event } = req.body;
57

58
  console.log(
59
    `Receiving ${type} request for ${event.broadcaster_user_name}: `,
60
    event
61
  );
62

63
  res.status(200).end();
64
});
65

66
const listener = app.listen(port, () => {
67
  console.log("Your app is listening on port " + listener.address().port);
68
});

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