README

npm (scoped) NPM npm

Gulel - Local Server for Twitch Webhooks

Gulel is an express based application server that manages Twitch Webhooks with minimal setup. It uses ngrok to make the local server reachable by Twitch servers.

It handles most of the stuff automatically for you.

It creates the HTTP endpoints needed by Twitch.
It verifies the payload received on the HTTP endpoints.
It creates the subscriptions by calling Twitch API.
It renews the subscriptions on expiry.
It stops the subscriptions by calling Twitch API when the server is shutting down.

Note: As of April 30, 2020, all Helix endpoints require OAuth and matching client IDs. See this announcement for more details. Gulel is already compatible with the changes announced.

Installation

npm install gulel

Usage

Gulel is an express based application server with additional methods for handling Twitch Webhooks.

Importing the module

const gulel = require('gulel')

Listening for a Webhook

gulel.subscribe('/users/follows?first=1&to_id=1337', (data) => { 
    // data passed from Twitch is available as an argument

    console.log(data)

    /*{
      "data": [
          {
            "from_id": "1336",
            "from_name": "ebi",
            "to_id": "1337",
            "to_name": "oliver0823nagy",
            "followed_at": "2017-08-22T22:55:24Z"
          }
      ]
    }*/
})

This creates a new route for the subscription on the express server. It starts listening for both GET & POST calls. GET method is needed by Twitch to confirm the subscription. POST method is to receive data from Twitch.

Each subscription is automatically subscribed when the server starts and renewed around 1 minute before they expire. The default expiry is set at 1 hour.

/users/follows?first=1&to_id=1337 is the topic to subscribe to. More topics are documented at dev.twitch.tv.

Starting the server

gulel.start({
  twitch: {
    accessToken: '<access token>',
    clientId: '<client id>'
  },
  server: {
    port: 3000
}, () => console.log('Gulel is listening for Twitch calls'))

// Output
// Gulel is listening at https://39697b582cd8.ngrok.io -> http://localhost:3000

This starts the express server on a port configured with routes for the subscriptions mounted. The express server is also available on the internet as a subdomain for ngrok.io and therefore, the local server is reachable for Twitch servers to send data.

Shutting down the server gracefully

Type quit in the terminal where the server is running and press enter. This will also unsubscribe from any active subscriptions.

Gulel is shutting down
Unsubscribing from active subscriptions

Also, gulel.shutdown() can be used to shut it down.

Examples

Few examples are available in the examples directory.

Configuration

Twitch

twitch.secret

This secret will be used as hub.secret while creating subscriptions. If not configured, the application will generate one.

twitch.lease

This value will be used as lease_seconds when subscribing to a Twitch event. Value is in seconds and default is 3600 i.e. an hour.

twitch.accessToken

User's Access Token for authenticating Twitch APIs.

twitch.clientId

Client ID for the Twitch application.

Tip! If you want to try out the server without creating a Twitch application, you can use an online token generator to get an access token and client id. This will also help you to get an access token with the scopes needed by some subscriptions.

Server

server.port

Local port number where the server will listen on. Should be a number. Default is 3003

server.tunnel

If true, ngrok service will be used. The default value is true

server.baseUrl

If set, the value will be used as the base URL for Twitch subscription callbacks.

Fixes & Improvements

Head over to the issues tab at github.com to report a bug or suggest an improvement. Feel free to contribute to the code or documentation by creating a pull request.

Sponsor

If you find the project interesting or helpful, please consider sponsoring it at github.com.

Usage no npm install needed!