Webhook

Twitchfy allows to listen events through Webhooks. By default an express server is required to handle the incoming events from Twitch. Nevertheless, an alternative will be explored in this guide.

Creating a Webhook

To create a Webhook firstly we have to initialize a server to receive incoming data. To do this we are going to use Express.

webhook.ts

import express from 'express';

const server = express();

Having created an express server we are going to use it to create a new WebhookConnection.

webhook.ts

import express from 'express'
import { WebhookConnection } from '@twitchfy/eventsub';

const server = express();

server.listen(3333);

const connection = new WebhookConnection({
    clientId: 'clientId',
    clientSecret: 'clientSecret',
    appToken: 'appToken',
    maintainSubscriptions: false,
    secret: 'myAwesomeSecret',
    baseURL: 'https://mybaseurl.com'
}, server)

connection.start();

As you have seen, to create a WebhookConnection we need a secret. It is important to notice that is not the same as the clientSecret, the secret is used for protecting your webhook from malicious attacks. The baseURL field is your own url that will point at your server, it has to use a https protocol.

Tip

For maintaining subscription between processes see Subscription Reload.

To wait until the connection is fully operational you can either wait until the start method promise is resolved or listen to ConnectionReady event.

webhook.ts

import express from 'express'
import { WebhookConnection, Events } from '@twitchfy/eventsub';

const server = express();

const connection = new WebhookConnection({
    clientId: 'clientId',
    clientSecret: 'clientSecret',
    appToken: 'appToken',
    maintainSubscriptions: false,
    secret: 'myAwesomeSecret',
    baseURL: 'https://mybaseurl.com'
}, server)

server.listen(3333);

connection.start().then(() => console.log('Connection ready'));

connection.on(Events.ConnectionReady, () => {
    console.log('Connection ready x2')
})

Subscribing to events

Having created a functional Webhook connection it is time to subscribe to our first event.

This example will show how to subscribe to a StreamOnline event.

webhook.ts

import express from 'express'
import { WebhookConnection, Events } from '@twitchfy/eventsub';

const server = express();

server.listen(3333);

const connection = new WebhookConnection({
    clientId: 'clientId',
    clientSecret: 'clientSecret',
    appToken: 'appToken',
    maintainSubscriptions: false,
    secret: 'myAwesomeSecret',
    baseURL: 'https://mybaseurl.com'
}, server)

connection.start().then(() => console.log('Connection ready'));

connection.on(Events.ConnectionReady, async() => {
    console.log('Connection ready x2');

    await connection.subscribe({ type: SubscriptionTypes.StreamOnline, options: {
        broadcaster_user_id: 'userId'
    }})
})

Danger

It’s crucial to subscribe to events when the connection is fully estabilished. If not the package will likely throw an error.

Tip

You can subscribe to multiple events at once using subscribeAll method.

Listening events

Now that you have created a new subscription we will listen to it and get notified whenever it is fired.

To achive this we can either use a callback using the onMessage function in the subscription object or using the SubscriptionMessage event.

Callback

webhook.ts

import express from 'express'
import { WebhookConnection, Events } from '@twitchfy/eventsub';

const server = express();

server.listen(3333);

const connection = new WebhookConnection({
    clientId: 'clientId',
    clientSecret: 'clientSecret',
    appToken: 'appToken',
    maintainSubscriptions: false,
    secret: 'myAwesomeSecret',
    baseURL: 'https://mybaseurl.com'
}, server)

connection.start().then(() => console.log('Connection ready'));

connection.on(Events.ConnectionReady, async() => {
    console.log('Connection ready x2');

    const subscription = await connection.subscribe({ type: SubscriptionTypes.StreamOnline, options: {
        broadcaster_user_id: 'userId'
    }})

    subscription.onMessage((message) => {
        console.log(`${message.broadcaster.displayName} has started a stream at ${message.stream.startedAt.toLocaleDateString()}`)
    })
})

SubscriptionMessage

webhook.ts

import express from 'express'
import { WebhookConnection, Events } from '@twitchfy/eventsub';

const server = express();

server.listen(3333);

const connection = new WebhookConnection({
    clientId: 'clientId',
    clientSecret: 'clientSecret',
    appToken: 'appToken',
    maintainSubscriptions: false,
    secret: 'myAwesomeSecret',
    baseURL: 'https://mybaseurl.com'
}, server)

connection.start().then(() => console.log('Connection ready'));

connection.on(Events.ConnectionReady, async() => {
    console.log('Connection ready x2');

    await connection.subscribe({ type: SubscriptionTypes.StreamOnline, options: {
        broadcaster_user_id: 'userId'
    }})
})

connection.on(Events.SubscriptionMessage, (message, subscription) => {
    //checks if the subscription is the desired subscription
    if(subscription.checkSubscriptionType(SubscriptionTypes.StreamOnline)) console.log(`${message.broadcaster.displayName} has started a stream at ${message.stream.startedAt.toLocaleDateString()}`)
})

Custom Server

As mentioned at the start of this section, the package has been made to be used with an express server. Furthermore, there is a way to use another type of server which doesn’t implies it has to be created with express.

To achive this we are going to use the post function from the connection object to send the data we have received from our server. By default the events will be sent to the base url callback +/subscriptions route. Althrough you can customize it in the subscriptions options by setting the subscriptionRoute option. To see the full url where the events will go you can access to WebhookConnection.url field.

In this example we are going to use the node native module https.

webhook.ts

    import { WebhookConnection, Events } from '@twitchfy/eventsub';

    const server = express();

    const connection = new WebhookConnection({
        clientId: 'clientId',
        clientSecret: 'clientSecret',
        appToken: 'appToken',
        maintainSubscriptions: false,
        secret: 'myAwesomeSecret',
        baseURL: 'https://mybaseurl.com'
    })

    http.createServer(async(req, res) => {
        if(req.url === connection.subscriptionRoute && req.method === 'POST'){
            let body = ''
            req.on('data', (chunk) => {
                body += chunk.toString();
            })
            req.on('end', async() => {
                return await connection.post(req.headers, JSON.parse(body), (c) => {
                    res.writeHead(200, {'Content-Type': 'text/plain', 'Content-Length': c.length })
                    res.write(c)
                    res.end();
                }, () => {
                    res.writeHead(200).end();
                })
            })
        }
    }).listen(3333)

In this example the post function is used whenever you receive a post request to the subscription route. The post function sends the package the data that has been received. The first callback which has a challenge parameter is fired whenever the webhook callback needs to be verified. The second callback is used whenever the package has received the data and checked the secret signature.

In the challenge callback you will have to respond to the request with a 200 status code and send the challenge param. Furthermore you have to change the Content-Type header to text/plain and the Content-Length header to the length of the challenge param.

In the success callback you will have to send a 200 status code to Twitch to indicate that all is ok and you have received the event.

Note

There is a third callback whenever the secret signature could not been verified.

If you fail to respond to the challenge callback no events notifications will be sent to you. Furhtermore, if you fail to respond to the success callback Twitch will try to resend the event continously and finally will revoke the subscription.