Gulel is an express based application server that manages Twitch Webhooks with minimal setup

Usage no npm install needed!

<script type="module">
  import gulel from '';


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.


npm install gulel


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


      "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

Starting the server

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

// Output
// Gulel is listening at -> 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 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.


Few examples are available in the examples directory.




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

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.


User's Access Token for authenticating Twitch APIs.


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.



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


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


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

Fixes & Improvements

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


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